Jean-Luc Thiffeault's Homepage

Git, GitLab, and GitHub

Git is a software tool for project development, where a project can be a paper or computer code or both. It is very convenient for collaborating: it allows several people to work on the same project together simultaneously. Unlike Dropbox, with Git users choose when to "push" their changes to the server and share it with others, so code or documents don't get stuck in an intermediate state. Two users can even make changes to the same file at the same time, and the version manager will merge the changes (up to a point). Users write log messages to go with their changes, which explain to their collaborators what the changes are. The history of the entire project is thus retained and annotated.

GitLab is a cloud-based service that hosts Git repositories. Git and GitLab work hand-in-hand. GitHub is a more popular cloud-based service, it didn't use to allow free private repositories so I only use it for open-source projects, such as braidlab. GitLab has the further advantage that it's open-source, so if the website goes away it is still possible to set up a GitLab server.

Setting up Git and GitLab (Linux and Mac)

  1. Sign up for a free account.
  2. Git may already be installed on your computer: open a terminal window, type git, and see if you get a usage message.

    Otherwise, download and install Git on your computer. On Ubuntu and Debian Linux, this is as simple as
        $ sudo apt install git

  3. Create a Secure Shell (SSH) key, by typing:
        $ ssh-keygen
    Press enter to accept the default. (If asked to Overwrite, you already have a key and can answer no.) Then type a passphrase (twice), which is like a password except that spaces are permitted.
  4. Log in to your GitLab profile, and go to SSH Keys.
  5. In the Key box, paste the output of
        $ cat ~/.ssh/
    This should be a long string of nonsense, beginning with ssh-rsa. This is your public key. The private key (same file but without the .pub extension) should never be shared with anyone.
  6. Repeat steps 2 to 5 for each computer you use. Alternatively, you can copy the files ~/.ssh/id_rsa and ~/.ssh/ to the .ssh forlder on other computers you use. Then you don't have to add other keys to GitLab.

The SSH key you uploaded will allow a secure connection between your computer and GitLab. On a typical Linux setup, you will only need to type in your passphrase once per session.

Using Git

  1. The very first thing to do, unless you don't plan on making changes or sharing them with others, is to set up your local Git username and email.

        $ git config --global "Eddie Shore"
        $ git config --global
    where you substitute your own name and e-mail address. Make sure to use an e-mail you registered with GitLab.

  2. To get a list of basic Git commands type

        $ git
    by itself. To get help on a specific command, type
        $ git help <command>

  3. To get a local copy (a clone) of a Git/GitHub project (also called a repository) such as the rodent C++ library, type

        $ git clone git://
    rodent is publicly available, so no password is needed. For private projects, if you have access to the project, you will be prompted for the passphrase associated with the key you created above. You only need to enter this passphrase once per session.

    By default, the clone command creates a subdirectory rodent in the directory where you ran the command, but you can specify an optional target path.

    The URL syntax is slightly different for a Git/GitLab project such as this sample project:

        $ git clone
    Notice the git@ instead of git://. You can find the required URL in either GitHub or GitLab under a "clone" drop-down menu.
  4. Now you have the entire history of the project available, but by default you will see the latest version. You can edit the files and make changes as usual. If you want to add a new file or directory, just create it as you normally would, and then explicitly tell Git about it with

        $ git add <new_file_or_dir>

    Note that new additions don't take effect until you commit them, as described below.

  5. If a file already existed before you made some changes, you need to explicitly "stage" those changes for addition:
        $ git add <existing_file_with_changes>
    If you make subsequent changes to the same file, they will not get committed in the next step. (Note that this works differently from other version-control programs, such as Mercurial.)
  6. To "commit" local changes once you're satisfied with them, use

        $ git commit
    An editor will pop up for you to enter a log comment (save and exit when done). If the log comment is short, you can specify it directly on the command line:
        $ git commit -m"Added file new_file_or_dir, which does stuff."
    Write something descriptive (if you use several lines, the first line should be a summary that stands on its own), and a new revision is created (also called a changeset). Revisions can consist of several additions, deletions, and/or modifications of files in the project.

  7. Unlike Subversion and many other version control systems, in Git commits are not uploaded to the server automatically. This encourages 'small commits' with well-defined changes. When you are ready you can upload all your commits by issuing

        $ git push
    Note that this assumes your project was cloned from a remote repository, rather than initialized as a new, fresh project.

    To make sure you have the latest version when you return to a project that you previously cloned, execute the pull command:

        $ git pull
    from within the local project directory.

  8. If someone else pushed changes, you might get a message when you pull that a merge is needed. Most of the time, simply issuing

        $ git merge
    will merge your current state with the changes. Note that you then have to commit again:
        $ git commit -m"Merged changes."
    The reason for this extra commit is that the merge might require some tweaking to make sure everything works (code is not broken, etc.), so Git adds this extra step to allow the user to intervene before accepting the merge.

  9. Other useful Git commands include

        $ git status
    which gives "status report" of the current state of your local files, and
        $ git diff
        $ git diff paper.tex
    which lists the differences between a local file and the original file. It is also useful to view the change history (or log) for a file or directory:
        $ git log paper.tex
    Finally, to remove a file or directory run
        $ git rm paper.tex
    which deletes the file, but will also delete it for you collaborators when they pull changes from the server. Note that removals should be explained in the commit log message (as should everything else!).

Some tips:

Advanced Features

For more information see the Git Book.