# git basics ## for beginner-level git users notes: - `make -B` to create images - two terminals each with same tmux session, increase font size - `export LANG=en_US.UTF-8` - `export PS1="\\[\\033[0;36m\\]\\w\\[\\033[0;35m\\]\$(__git_ps1 \" (%s)\")\\[\\033[0;36m\\] $ \\[\\033[0m\\]"` - remove git config for demo - log in to git.idiv.de - cheat sheets are handed out later - if you have questions feel free to interrupt - cleanup https://git.idiv.de/sc/edu/git-merge-conflict-demo

## goals 1. use git in **ALL** your projects 1. collaborate with each other ... is mission accomplished. notes: - there is time for fancy stuff later - take a few weeks getting used to git - delay is good to grow your own experience - growing pain is how we learn

## agenda (today) 1. motivation 1. install and setup 1. recording changes 1. platforms and remotes 1. collaboration note: - we have dynamic breaks, try at most 90 minutes without break

## agenda (advanced) 1. customization (editors, IDEs) 1. project & team setup (GitLab) 1. how to project maintainer 1. automation note: - in smaller groups - while today is more general, advanced will be focused on your specific situation

## about version control > records changes what, who, when, why note: - different kinds of version control systems - for different meta-level things - git is for text files / source code

## about git ### best tool for the job - simple by design - powerful if needed - documentation - industry standard notes: - git name: "the stupid content tracker" - today we talk about the simple parts - powerful parts in advanced course - doc: also means community / stackoverflow entries

## about christian - [scientific computing support @ iDiv](https://www.idiv.de/en/about-idiv/support-for-scientists/scientific-computing.html) since 2014 - happy git user since 2010 > There will never be a better version control system than git. > > -- Christian Krause, 2017

## about you ![people](img/people.jpg) name, job, git experience, why git? notes: - re-seat everyone based on command line experience

# motivation > Why should ***I*** use version control? notes: - summarize reasons from audience - highlight that motivation chapter is more about the concept of version control in general, not git specifically, because git is just a tool to do it

## motivation #1 ### avoid mess ![blah](img/motivation-draft-mess.png) notes: - who has seen such a mess? - who has contributed to such a mess? - who has created such a mess?

## motivation #1 ### want structure ![blah](img/motivation-structure.svg) notes: - structure - who, when, why - ability to inspect old versions - ability to revert to old versions

## motivation #2 ### throw-away playgrounds ![playground](img/motivation-throwaway-playground.svg) notes: - test stuff without interfering - throw away if garbage - integrate if good - switch back and forth without pain

## motivation #3 ### collaboration made easy > This text cntains a typo. notes: - demo **edit** ribbon - change target branch (creates MR) to: **basics/typo** - commit message: ``` fixes typo learn how to use a spell checker, dude! ```

## motivation #3 ![typo-pr](https://pbs.twimg.com/media/EDsklbLUEAMdusJ.png) notes: - might not seem like much - but you are still making the world a better place - and it is not too much effort

## motivation #a ### automation - ***quality assurance*** - **static code analysis** aka *linting* - **testing** (unit, integration, regression) - enforce **style guide** aka *code formatting* - ***deployment*** (app store, web server) *(see advanced)* notes: - buzzwords: - continuous integration (CI) - continuous deployment (CD) - pre-commit hooks - basically, everything you can script

motivation #wars

1. revert a bad change? 1. view the history? 1. know why someone changed it? 1. maintain multiple versions? 1. see the diff of two versions? 1. find commit that broke something? 1. have free backup? 1. have non-interfering playgrounds? 1. have automated testing? 1. have automated deployment? 1. forget about ms word comments? 1. contribute to a project? 1. share your code? 1. let other people do the work for you?

# install

## command line ![just take the damn red pill](img/matrix-pill.jpg) notes: - learn by doing / understand what you do - GUI hides too much of that - use GUI only if it integrates well in your workflow, e.g. IDE - my main editor is emacs, so I am using emacs integration (magit) for most of my day-to-day tasks, only a few key presses per git operation, when I am in the terminal, I simply use the CLI

## os packages - **Linux:** `bash` and `git` - **Mac:** `bash` and `git` - **Windows:** [git bash](https://git-scm.com/download/win) notes: - **Windows Subsystem for Linux (WSL)**: we do not use it because it cannot use native Windows editors - **cmder**: we have tried it, it sucks

## os packages ### your turn 1. install git CLI 1. open terminal 1. type: `git version` notes: - we **need** git 2.23 for `git switch` and `git restore`

# setup notes: - add **break** here if needed

## command line ### description syntax ```bash # command git # sub-command git status # argument git diff README.md # optional argument git diff [--staged] ``` notes: - do not yet type along, we will tell you - do not type brackets they just mean argument optional

## command line ### bash basics ```bash pwd # print working directory ls [dir] # list directory contents echo msg # print message cd [dir] # change directory mkdir dir # create directory rmdir dir # remove directory rm file # remove file cp src dest # copy from source to destination mv src dest # move / rename ``` ```bash nano file # edit file (Linux / Mac) notepad file # edit file (Windows) ``` notes: - go through commands then everyone open terminal - create a directory - create README - rename directory - copy README to README.md - use autocompletion with tab - use bash history with cursor and ctrl+r - explain `.` and `..`

## command line ### git syntax ```bash # every git command git command [arguments] # get help git help [command] ```

## cheat sheet https://idiv-biodiversity.github.io/git-cheat-sheet/

## git setup #1 ```bash # configure your identity git config --global user.name "Jane Doe" git config --global user.email "jane.doe@idiv.de" # show colors git config --global color.ui auto # configure aliases git config --global alias.unstage "reset HEAD --" git config --global alias.lol \ "log --graph --decorate --oneline --all" # show config git config --list [--global] ``` notes: - hand out cheat sheets **now** - for Windows: check that `core.autocrlf true`, but do not waste time explaining it for everyone

## git setup #2 ```bash # Windows git config --global core.editor notepad # Mac git config --global core.editor "open -Wne" # Linux GNOME / KDE git config --global core.editor gedit git config --global core.editor kate # to verify editor works git config --global --edit ``` notes: - if you already have another *core* editor for yourself, feel free to use it - if not, please stick to a simple-to-use one for the duration of the seminar

# git command line ## local repositories notes: - add **break** here if needed - this section has demo and interactive part

## command line ### create repositories ```bash # create empty repository git init project-name # create repository from existing project # which is not under version control cd path/to/project git init ``` notes: - this is an explanation slide - for this tutorial we are creating a new repository - at home you can `init` your existing projects *without* version control

## create a repository ### your turn 1. create a project called **hello** 1. write a short `README` file notes: - mention cheat sheet - switch to terminal after a while and demo solution ```bash mkdir ~/projects git init hello cd hello $EDITOR README.md ```

## command line ### git status ```bash # show status and what to do git status ``` notes: - important git command - shows a lot of information - shows basic git commands - later, we will see different outputs

## the staging area ![staging area](img/staging-area.svg) notes: - **do not demo here! that is done during next slide, this one is about the concept of the staging area** - **call for attention, this is important** - in a local git repository, content can be in three stages - make local changes, these are **not yet** known to git - **prepare** commit adding more and more **changes** - **commit** this **set of changes** - commit **should be a logical unit** of changes - the deciding feature of a git (G)UI is how it handles the stage, i.e. if you cannot interactively stage/unstage hunks, the UI sucks

## command line ### file handling ```bash # use staging area git stage file git unstage file # discard changes git restore file # rename and remove git mv source destination git rm file ``` notes: - users should do this in a terminal with demo by us - `git stage` and `git add` are the same thing - prefer `stage` and `unstage` because the opposite of `add` is `rm` and that does something entirely different

## command line ### show changes ![git diff](img/staging-area-diff.svg) notes: - users should do this in a terminal with demo by us - make a round and check

## command line ### commit changes ```bash # opens editor for you to edit commit message git commit [-v] # commits with a short message git commit -m "initial commit" ``` notes: - users execute commit after next two explanation slides

## commit messages ![software licenses](img/xkcd-1296-git-commit.png)

## commit message conventions ```markdown this is a short subject line This is the body. Notice that the subject line is short and to the point. The body may explain in more detail why this change was introduced. - do not list which files changed - the diff already tells that References to issue trackers should be in the very end, e.g.: fixes #42 ``` notes: - be concise - empty line after subject - wrap 72 characters - remember: commit = logical unit - the diff tells you what changed, describe why it changed - decide with your team, write `CONTRIBUTING.md`

## command line ### view history ```bash # show all commits git log # show all commits plus diff git log --patch # shows condensed view of history, i.e. # - only commit message subjects # - one per line git lol ``` notes: - make a round and check

## you can now - create local repos (`init`) - track changes in your projects (`stage`, `commit`) - browse your projects history (`log`) - rest are helpers (`status`, `diff`, `restore`) notes: - very important: `status` - demo emacs git integration to show `stage -p`

## goals 1. use git in **ALL** your projects ✓ 2. collaborate with each other

# project licenses ## aka legal shit notes: - non interactive section - add **break** here if needed - unfortunately, we have to talk about this - go back to initial commit - initial commit should contain not just readme but license, too

## no license - exclusive copyright to **each!** author - **no one** can use, copy, distribute or modify

## software licenses ![software licenses](img/license-chooser.svg) notes: - there are closed source licenses as well, ask your legal department about those

## other licenses - media, documentation: creative commons - paper / thesis: journal vs legal department

## guide https://choosealicense.com

# distributed ## version control system notes: - add **break** here if needed

## git usage until now - has all been local - repo contains entire project history - not yet answered: - how to use remotes - how to collaborate notes: - collaboration needs remote repositories - by-product of remotes is backup - ideally, `~/projects` needs no backup because **every** project is under version control and has a remote

### how do i get remotes? # web apps - GitLab demo - GitHub (no demo) notes: - log in - create project - push / pull

## connecting remotes ```bash # get fresh clone git clone url # add remote to existing repository git remote add name url ``` note: - show both commands in web interface when creating new repository - explain HTTPS and SSH URLs - for seminar, we will stick to HTTPS - you can set up password manager integration later, git integrates well with the common ones

## remote ### interaction ![remotes](img/git-remote-solo.svg) notes: - remotes have names, default to **origin** - remotes are usually **full clones**, i.e. entire history, all commits, all branches - **fetch** edge is on the box, so you fetch **everything** - **fetch** does not integrate branches, i.e. no **merge** - **push** and **pull** also **merge** the *tracking* branch

# branch and merge notes: - this is a demo chapter, you will all do this in collaboration chapter (next one) - what was this **main** again? we have not explained yet

## branches visualized ![playground](img/motivation-throwaway-playground.svg) notes: - we can take a lot away from this small example - create a branch to have a separate history - branch is a name attached to a commit - the name advances when a new commit is made - **main** is a naming convention for the default branch - switch back and forth - always imagine git history as a directed graph - graph is drawn with new top and old bottom - commit points to its parent - git commands modify the graph

## when to use branches - breaking **main** - something takes longer - frequent interruptions - (instead of) comment out code notes: - if logical commit without breaking do not branch

## branch commands ```bash # show your local branches git branch # show all branches (remotes, too) git branch --all # create a new branch git branch name # switch to a branch git switch name ``` notes: ``` # branch, branch --all git lol # show branches # branch wip/feature, lol # switch wip/feature, lol # edit, commit, lol # push, lol ``` - always `lol` because visual representation helps understanding

## branch naming ### conventions ```bash # slashes for categories hotfix/42 release/1.6.0 # dashes in names wip/font-changes # nesting is allowed topic/ui/input-form ``` notes: - `git branch --list "topic/*"` - decide with your team, write `CONTRIBUTING.md`

## resolving branches ```bash # resolve branch by merging git switch main git merge branch-name # delete branch git branch -d branch-name ``` notes: ``` # switch main, lol # merge wip/feature, lol # branch -d wip/feature, lol ```

# collaboration notes: - add **break** here if needed - we: create new repo - group: fork and clone, remote add upstream, lol - next slide, explain img

## view of contributor ![remotes](img/git-remote-contributor.svg) notes: - we: new commit - group: fetch, lol, pull upstream main, lol - group: push origin, lol - group: branch, switch, commit, push, MR - collaboration happens in issues and MR discussion! - we: review and possible resolve merge request in GL - show next slide once merging is done on command line - we: review one MR, show line comments in GL, thumbs up - advanced: view of maintainer

## criticism / commenting - **positive**: leave a star, blog about it - **negative/destructive**: keep it to yourself! - **constructive**: issues and merge requests! - check if already reported - emote if you agree - discuss if you disagree notes: - issues / requests are supposed to be technical - avoid **#metwo**, this is annoying for maintainers, use emotes - rule: comment only if you have something new to add to the discussion

## resolving conflicts ```bash git fetch upstream git switch topic/feature git merge origin/main # fix conflicts git push ``` notes: - https://git.idiv.de/sc/edu/git-merge-conflict-demo - contains two conflicting branches - git lol - git fetch - explain different solutions - create MR - MR status show merge conflicts - edit file, show how to keep both ours and theirs

## you can now - create and connect to remotes (`clone`, `push/pull`) - contribute to projects (`switch -c`, `push -u origin`, MR/PR) - hint: use `lol` alias

## goals 1. use git in **ALL** your projects ✓ 2. collaborate with each other ✓

# "homework"

## "homework" #1 ### use git for each project you use ... ... create repository in GitLab ... ... commit and push changes! notes: - you will have problems - because we only taught the basics - use documentation or ask us - the advanced seminar will be about some of the techniques - TODO visualize these notes with fisherman vs deep sea fishing

## "homework" #2 ### collaborate - talk with your colleagues - organize project(s) you use together - open issues for problems and features - contribute via merge requests - review commits and merge requests - ask others to review your contributions

## "homework" #3 ### feedback https://git.idiv.de/sc/edu/git-seminar notes: - remember code of conduct, criticism and commenting rules

## agenda advanced 1. customization (editors, IDEs) 1. project & team setup (GitLab) 1. how to project maintainer 1. automation note: - in smaller groups - while today is more general, advanced will be focused on your specific situation

EOF

# backup slides

## rebasing ### as maintainer ```bash git remote add alice https://... git fetch alice git rebase [--interactive] main alice/topic/feature # fix conflicts git push # manually close merge request ``` notes: - manually close merge request because no merge commit

## rebasing ### as contributor ```bash git fetch upstream git rebase origin/main topic/feature # fix conflicts # force push because branch history changed git push --force ```

## view of maintainer ![remotes](img/git-remote-maintainer.svg)

## review ### code of conduct 1. be friendly 1. be responsible 1. be open 1. be proactive notes: - the discussions are usually public, so be aware of that - usually needed when community grows - decide with your community, write `CONTRIBUTING.md`

## resolving conflicts ```bash git remote add alice https://... git fetch alice git switch main git merge alice/topic/feature # fix conflicts git push ``` notes: - maintainer decides if trivial or delegate to contributor