Skip to content
Snippets Groups Projects
README.md 3.64 KiB
Newer Older
Fabien Maussion's avatar
Fabien Maussion committed
# Git workshop

**Welcome!**

These notes are written in the [Markdown](https://www.markdownguide.org/basic-syntax/) format. 

## Git, gitlab, github?

`git` is a version control tool.

You can install it with:
- `brew` or `apt` on Mac, Linux
- https://gitforwindows.org with the `git bash` programme (my recommendation)

GitLab, GitHub are online services built around git. Nowadays they provide much more than pure version control.

GitHub has been bought by Windows a while ago.

GitLab is an "open-core" company. gitlab.com is very much like github. git.uibk.ac.at is a local gitlab server and is only good for local university projects. You can move repositories around, so starting at UIBK and then move to gitlab.com is always an option.

## Examples of utilization of gitlab/github

Project management:
- https://git.uibk.ac.at/acinn/it-projects
- https://github.com/GLIMS-RGI/rgi7_scripts/projects/1

Website:
- https://github.com/OGGM/oggm.github.io
- https://github.com/OGGM/tutorials
    - jupyterbooks (makes webpages from jupyter notebooks)
- https://github.com/OGGM/oggm-edu
- https://git.uibk.ac.at/acinn/stations-metadata
    - static webpage generator inside (e.g. jekyll, pelikan)

Publication:
- Works only nicely with Latex or text based editors
- Overleaf / HackMD <-> GitHub sync 

Code:
- https://github.com/OGGM/oggm
- all of GitLab / GitHub

## Not so nice with git

- Pictures, data, binary files
    - if you change a picture, netCDF file, can not understand the actual differences between the versions
- Branches and collaborative is quite a learning curve (worth it though)
- people working on the same script might result in conflicts which are sometimes complicated to solve (note that this is the very nature of conflicts - if fact git is trying to help us here)
- fit GUIs are confusing (I recommend to learn with the command line first)
- sometimes issues with cloud data storage (e.g., pClouddrive) for commits
- First collaboration among people can become caothic
- if you do something slightly different than your "normal" workflow, you might get "errors" or "warnings", so you might feel "afraid" that you do something wrong when "forcing" something ... 

## Not so nice with gitLab

- slightly more complex if people outside of the university want to join 


## Getting started with git

- you always want a local + online version of git
- when created, do git clone ... in the terminal with the "clone with HTTPS" path
    - if you do not want that you have to write the password every time, use SSH, but need to exchange "keys" for each machine where you use it
    - Gitlab e.g. https://docs.gitlab.com/ee/ssh/

- holy trinity of git: git fetch (information), re-doing git status will show changes, then git pull, git commit, git push
    - `git commit -a -m`
- `git status` tells you what changed 
- add new file with `git add` + filename
- git switch -


**The four commands which go online:**
- `git clone` `git pull` `git fetch` `git push`

## Additional tools/information

- Github to Zenodo integration (uses tags, i.e. name to specific commit to create DOIs)

## Collaborations
- Branches for collaborations

Collaborating:
- Upstream Repo (Main Repo, "the Holy one" the one you don't want to force push)
- Fork (named Origin) to clone from, i.e. Local Repo (where you add your changes ideally in a dev branch)
- Push changes to origin (fork), from that create pull request to Holy Repo

What happens when there are changes at the Holy Repo?
- git fetch upstream (from Main aka Holy Repo), git pull on clean master branch (not on dev branch)
- Best option is git rebase from dev to local master (avoid git merge)
- If conflicts arise you have to solve them (online or locally)