Jean-Luc Thiffeault's Homepage

Git and GitLab

Git is a software tool for project development, like a paper or computer code or both. It is very convenient for collaborating: it allows several people to work on the same project together. Unlike Dropbox, users choose when to "push" their changes to the server, 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 were. The history of the entire project is thus retained and annotated.

GitLab is a cloud-based service that hosts Git repository. Git and GitLab work hand-in-hand. GitHub is a more popular cloud-based service, but it does not allow free private repositories so I only use it for open-source projects, such as braidlab.

There are many other version-control programs (RCS, CVS, Subversion, Bazaar, ...). I used to use Mercurial, but since Git is becoming the dominant program I'm now slowly migrating to Git. I still think Mercurial is better and simpler for small projects, however. Here are the old instructions for using BitBucket and Mercurial.

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 what happens.

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

  3. Create a Secure Shell (SSH) key, by typing (in Linux or Mac):
        $ 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/id_rsa.pub
    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/id_rsa.pub to the other computers. 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 user.name "Eddie Shore"
        $ git config --global user.email eshore@oldtimehockey.edu
    
    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 thecommand

  3. To get a local copy (a clone) of a Git project (also called repository) such as rodent, type

        $ git clone git@github.com:jeanluct/rodent.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.

  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 next.

  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 differs from the way other version-control programs work, 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 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
    or
        $ git diff paper.tex
    which lists the differences between 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 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.