Git for Mathematicians (3a): The Practice [setup and init]

Part 1: Preliminaries
Part 2: The Theory
Part 3a: The Practice


This post is still a work-in-progress.

After a long hiatus, here is the third part of my series of posts about Git for Mathematicians πŸ™‚. I explain the basics of how one would go about using Git to write a math paper. If you have not read the previous parts of the series, you can find them there:

I will mainly use GitHub as a remote, but feel free to use anything you want (Bitbucket, GitLab…).


I will assume some level of familiarity with using a terminal to run commands. If you are not comfortable with that, then I suggest that you wait for the “Bonus” part of the series, where I will mention some alternatives, including GitHub Desktop and Visual Studio Code.


The first thing to do is setup your environment. You will, of course, need to install Git. This is dependent on your OS:

Before going further, you should also configure your name and email, as otherwise you will not be able to commit anything. This will also serve as a test run to see if you are able to run the Git commands. To configure your contact details, run the following commands in a terminal (replace “Your Name” and “” by your own name and email, but keep the quotes):

# run the following commands in a terminal
git config --global "Your Name"
git config --global ""

Note that these commands are typical of how most Git commands work:

Running these two commands will change Git’s global configuration file for your account. This file, called .gitconfig, is located in your user’s home directory (usually /home/[user] on Linux, or C:\Users\[user] on Windows). Afterwards, the file should look like this:

email =
name = Your Name


As I explained in my previous post, Git is structured around repository. A repository is just a folder (and its sub-folders) whose history is tracked by Git. The repository contains the files, the commits, the branches, and so on. There are essentially two ways to create a repository on your computer: either you can create a brand-new repository that you can then push somewhere, or you can clone an existing repository. I will explain both options, starting with the (simpler) cloning.

Cloning a repository

Cloning a repository simply means creating a local copy of a distant repository. This local copy will contain (unless you choose otherwise) the full history of the repository, and the files tracked by Git in their latest state. You must be connected to the Internet (if the repository is online) and you must be able to read it if it is private.

If you have not already created a repository, you can create one on GitHub, as in the following screenshot:

Creating a repository on GitHub

You can either set it to public or private. Note the URL of your repository when it appears on the next screen (or use the one I provide below). Then, you can clone it with the following command:

git clone

This will create a new folder in the current directory called example-repository and copy everything from the remote repository into it. Afterwards, assuming that you cloned my example repository, your folders will look like this:

β”œβ”€β”€ .git/
β”œβ”€β”€ sample.txt
└── some-folder/
    └── other-sample.txt

As you can see, the folder contains two things:

You can now modify the files in this repository and use the commands from the next sections to track your changes. Everything is already set-up so that pushing and pulling works as expected.

Initializing a new repository

The other option, if you have no existing repository to clone, is to initialize a new one. The steps are simple:

  1. (Optional) Choose or create a folder that you want to track with Git.
  2. In the terminal, switch to that folder.
  3. Then type git init in the terminal.

In a Linux shell, this would typically look like this (feel free to change the name of the folder, of course):

# skip the first step if the folder already exists:
mkdir ~/papers/riemann-hypothesis # 1. create a new folder
cd ~/papers/riemann-hypothesis    # 2. switch to that folder
git init                          # 3. initialize the repository

Afterwards, your files should look like this:

β”œβ”€β”€ .git/
β”œβ”€β”€ other files (if some were already in the folder)
β”œβ”€β”€ ...........
└── other files

In effect, initializing just creates a .git folder with an empty history of commits. You are then free to work on the files and track your changes with Git. However, the remote(s) will not be set-up properly yet, so you will need to adjust that before being able to collaborate with other people and/or making backups of your repository.


Initializing will work incorrectly if the directory you are in, or a parent directory, is already a Git repository. In that case, take these steps to fix the issue.

More to come in a next post…

Further reading

Here are some more resources to learn using Git: