Version Control : git - Hydro-Informatics

The Concept¶

git is a fast, scalable, distributed revision (version) control system, originally developed by Linus Torvalds (read more about the git kernel). git enables to coordinate work among collaborators beyond programming, in any set of files. Its support of non-linear workflows, speed, and data integrity make git an indispensable tool in many industries and research. Before starting to read this git tutorial, have a look at the schematic functioning of repositories hosted with git.

git-scheme — The concept of git and basic vocabulary. The REMOTE frame is online (i.e., someone else’s computer) and the LOCAL frame is what happens on a personal computer, which is connected to the internet. Repositories can be newly created or forked remotely. Remote repositories can be cloned locally, modified locally, and local changes can be pushed to a remote repository. Collaborators want to make sure to regularly pull changes of a remote repository. Working with and on different branches becomes increasingly important with the number of developers and for the moment we just need to remember that we start working in the master branch (i.e., upstream origin / HEAD = main).

Install git¶

The materials provided with this eBook are best downloaded and updated using git-able environments (avoid downloading materials as zip file).

Linux

Windows

macOS

Although git is an integral feature of most Linux distributions, Debian users might still need to install it. For this purpse, open Terminal and tap:

sudo apt install git

macOS users may use Homebrew for installing git, but there are other options, such as Xcode.

To use Homebrew for installing git, start with installing Homebrew through the macOS Terminal:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

The installation of Homebrew may take a while. After the installation, make sure to export the required PATH variable (copy line-by-line):

echo 'eval $(/opt/homebrew/bin/brew shellenv)' >> /Users/$USER/.zprofile
eval $(/opt/homebrew/bin/brew shellenv)

It might be possible that the paths in the above commands need to be adapted to the directories that the Homebrew installer prompts at the end of its installation.

Finally, install git with Homebrew:

brew install git

Ultimately, Homewbrew provides many more packages, which are essentially useful for developers, such as ruby or React (go to the full package list).

Read more installation instructions and about options for git on macOS at https://git-scm.com/download/mac.

The repositories for this course are mainly hosted on GitHub. There are many other git service providers out there, such as GitLab, plan.io, or BitBucket.

Create a Repository¶

To create a git repository, make sure to have access to a git provider. The most popular way to get access to a git-able server is to register with one on the long list of popular git providers.

Clone (Download) a Repository¶

GitHub provides detailed descriptions and standard procedures to work with their repositories (read more). The following “recipe” guides through the first time download of git materials

Open your favorite git-able command line:
- Windows Options: PowerShell, Git Bash, or Command Prompt
- Linux: Terminal
Clone the course repository (change materials according to the course attended):
git clone https://github.com/hydro-informatics/materials (or whatever repository you want to clone)

Done.

Pull (Update/Re-Download) a Local Repository¶

git (within Git Bash, PyCharm, or Terminal) is the only option to update local copies of a remote repository consistently. To do so, open one of the above mention git-able command lines and do the following:

Go to the local directory of the repository with the cd command (e.g., materials):
cd "D:/Python/materials/" (or wherever materials was cloned).
git status - shows the modifications made.
Merge errors may occur when changes were made in the local copy. To avoid merge errors, type:
git pull --rebase - if locally edited scripts were modified remotely since the last pull, this will prompt issues and highlight problematic sections with >>> ). Manually open concerned files and resolve the issues (delete invalid >>> highlights).
git push

Done.

Update a Remote Repository (Push Local Changes)¶

After editing files in a repository locally, add - commit - push (in that order) your edits to the remote copy of the repository with version control. To add - commit - push local changes to a remote repository, make sure to be the remote repository owner or a contributor. Then open a git-able terminal and type:

git status - this shows the modifications made.
If the status looks OK with the consciously made changes, type git add .
Optionally, if only single files were changed, use git add filename.py instead. Best solution: use a local .gitignore file.
Commit changes git commit -m "Leave a message" - leave a significant and precise short message.
git pull --rebase - if locally edited scripts were modified remotely since the last pull, this will prompt issues and highlight problematic sections with >>>). Manually open concerned files and resolve the issues (delete invalid >>> highlights).
git push

Summary for updating a repository

Tap the following in Terminal or GitBash to upload all modifications in a local repository to the remote repository (make sure to know in which folder your repository is located on your computer - this defines what you need to enter for /change-directory-to/repository/):

cd /change-directory-to/repository/
git status
git add .
git commit -m "Leave a commit message"
git pull --rebase
git push

If any error occurs, carefully read why the error occurred and follow the instructions for troubleshooting (e.g., for setting up your user configuration with git config --global user.email “email@example.com”). You may ignore warning messages regarding line-end formats (WARNING ... LF endings ...) for most applications presented in this eBook.