Git Tutorial

• 1: Git installation
• 2: Collaborating on an existing project

1 - Git installation

Before you start using git for your Python projects or other collaborative purposes, you have to choose and set up an environment that allows you to work with git and install the latest version of git.

Git can be used through many different interfaces. Throughout this collection of resources we will predominantly be working with git in the command line in order to manage collaborative projects. To get started you’ll set up a command line interface, install git and optionally a gui. Gui’s are often helpful to check a projects branch structure and see which branches are merged, not merged and under development.

Linux

Checklist:

• git & git bash installed
• configured identity
• git command line interface personalized (optional)
• set-up user account on i.e. github or gitlab

If you want to install the basic Git tools on Linux via a binary installer, you can generally do so through the package management tool that comes with your distribution. If you’re on Fedora (or any closely-related RPM-based distribution, such as RHEL or CentOS), you can use dnf:

sudo dnf install git-all

If you’re on a Debian-based distribution, such as Ubuntu, try apt:

sudo apt install git-all

For more options, there are instructions for installing on several different Unix distributions on the Git website, at linux installation page.

Windows

Checklist:

• install VS Code editor (optional)
• git & git bash installed
• configured identity
• git gui installed (optional)
• git command line interface personalized (optional)
• set-up user account on i.e. github or gitlab

Editor: Visual Studio Code

If you are not familiar with vim, nano or other text editors used in the command line you can make access to git easier by installing the open-source text editor and Python IDE Visual Studio Code (VS Code). Download the windows version of VS Code, then run the installer. Accept most default configurations on all pages except for the following:

• (Optional) On the Select Additional Tasks page, check “Create a desktop icon” under “Additional icons”.
• Also on the Select Additional Tasks page check all four boxes under “Other”
  1. “Add ‘Open with Code’ action to Windows file context menu”
  2. “Add ‘Open with Code’ action to Windows directory context menu”
  3. “Register Code as an editor for supported file types”
  4. “Add to PATH” (this should be selected by default).

Git and Bash Shell

(Please note VS Code should be installed before this step.) There are multiple different ways to install git on Windows. I recommend installing the official and latest git version. It will come with a command line tool. Download the official windows installer form here, then run the installer. If you have not used git before, accept most default configurations on all pages except for the following:

• (Optional) On the Select Components page, check “On the Desktop” under “Additional icons”.
• On the Choosing the default editor used by Git page, think about which editor you’d prefer to use and feel comfortable using. “Use Visual Studio Code as Git’s default editor” from the drop-down menu if you are not comfortable yet using i.e. vim.

To check if your installation was successful open teh Git Bash program (if you checked the option you can find it as a new icon on your desktop). The type:

git --version

to check which version of git was installed. Then run the following commands, make sure you add your name and e-mail address, to let git know who you are:

git config --global user.name "Name Surname"

git config --global user.email "name.surname@examplemail.com"

MacOS

Checklist:

• commandline/ terminal available
• git installed
• configured identity
• git gui installed (optional)
• git command line interface personalized (optional)
• set-up user account on i.e. github or gitlab

Command line interface

Using the command line on MacOS is straight forward as MacOS comes with the Terminal already installed. The easiest way to open the Terminal is to search for it via MacOS Spotlight. Open spotlight by pressing cmd+space or navigating to the Search icon in the top right corner. Then look for the Terminal and double click to open.

Installing git

There are multiple ways to install git on MacOS and modern Macs ship with a pre installed version of git through the Xcode Command Line Tools. To check if git is installed type in your terminal:

git --version

If git is not already installed you’ll get prompted to install it. Follow the suggestions in the command line. Once the installation has finished, run the following commands, make sure you add your name and e-mail address, to let git know who you are:

git config --global user.name "Name Surname"

git config --global user.email "name.surname@examplemail.com"

Gui

In most cases, gitk, a gui to check your projects branch structure, will automatically be installed with git on MacOS. You can check if gitk is installed by typing:

gitk --all

A small separate pop-up window should open, either showing you the branch structure of the project - in case you opened gitk in a git directory -, or showing a message explaining that not git repository could be found.

There are many alternatives to gitk with more elaborative gui’s, i.e. gitdesktop. However, gitk provides all functionality needed for the beginning. of course there is also a way to check your branch structure directly from the terminal without a gui. You could for example inspect the output of:

git log --oneline

Trouble shooting

In case you have trouble accessing git via the commandline, try:

• Installing the latest version of Xcode through the app store
• Install git using Homebrew

Personalized command line interface

Personalizing your command line interface, for example, to show the branch name you are currently using, can make working with git much easier. Copy these following lines:

parse_git_branch() {
     git branch 2> /dev/null | sed -e '/^[^*]/d' -e 's/* \(.*\)/ (\1)/'
}
export PS1="\u@\h \[\033[32m\]\w\[\033[33m\]\$(parse_git_branch)\[\033[00m\] $ "

and past them to your ~/.bashrc file. Then restart your terminal, i.e. by typing source ~/.bashrc or opening and closing it.

Further reading and Sources:

• git
• resources to learn git

2 - Collaborating on an existing project

This section introduces you to getting started with BioPAL in git and gives you an example of a basic git workflow.

Setting-up, cloning an existing project

1. Navigate to the existing project on github in your web browser:

https://github.com/biopal/biopal

2. Create a fork of the project in your profile by clicking the fork icon in the top right corner and selecting you profile. This allows you to track your changes, and save them to your own profile before integrating them to the official version of the project.

3. Copy the link of your forked version of the project, found under the green code button on the right hand side:

https://github.com/YOURUSERNAME/biopal.git 

3. In the terminal, navigate to a directory you’d like to store your project in. You can for example create a new projects directory to store your git projects under. Type into git bash or terminal:

mkdir ~/projects # to create a directory
cd ~/projects    # to navigate to the directory

4. Clone the project using git clone <url>:

git clone https://github.com/biopal/biopal.git

This creates a new directory named ~/projects/biopal, initializes a .git directory inside it, pulls down all the data for that repository, and checks out a working copy of the latest version. If you go into the new biopal directory that was just created, you’ll see the project files in there, ready to be worked on or used.

5. Check your remotes by typing git remote -v into the command line. Your git remotes point to the online github repository and will help you synchronize with your online fork of the project. You will now set up your git remote, aiming for git remote -v to display:

origin	https://github.com/YOURUSERNAME/biopal.git (fetch)
origin	https://github.com/YOURUSERNAME/biopal.git (push)
upstream	https://github.com/biopal/biopal.git (fetch)
upstream	https://github.com/biopal/biopal.git (push)

It is likely that git remote -v will look more something like this:

upstream	https://github.com/YOURUSERNAME/biopal.git (fetch)
upstream	https://github.com/YOURUSERNAME/biopal.git (push)

We will first, need to rename upstream to origin which will point to your personal fork of the project created in step 2. Type:

git remote rename upstream origin

Check if upstream was renamed to origin typing git remote -v. Next we need to add a new upstream this will point to the original project you saw in step 1. To add an upstream type:

git remote add upstream https://github.com/biopal/biopal.git

Note depending on your access/ development rights in the origin project you may or may not be able to push to upstream. In general it is considered best practice to ALWAYS push to origin first, and then point a Pull Request to upstream if upstream is a collaborative project. To finish, verify that all changes were made successfully checking the output of git remote -v.

You are now ready to make your first changes!

Making changes in your project and adding them

General workflow:

1. Make sure you are on the right working branch or create a new branch: git checkout -b NEW
2. Make changes
3. Stage changed files for commit: git status (optional, to check changed files), git add <file_name>
4. Commit staged files and write a commit message: git commit -m "[ENH] my message"
5. Push commits in branch NEW to github origin: git push origin NEW
6. Create a PR pointing your branch NEW to your origin main or to the upstream main
7. Include changes in your local main branch: git checkout main, then git pull upstream or git pull origin
8. Repeat with step 1 or rebase your working branch NEW onto your local main and repeat with step 2: git checkout NEW and git rebase main NEW

Further Reading:

• Working with remotes
• Git basics
• Why branching