# git basics ## for beginner-level git users notes: - terminal session preparation: - two terminals each with same tmux session, check font size - remove user, host and path from prompt - clean git config for demo - close your laptops - hand out cheat sheets later, no need to write stuff down - if you have questions feel free to interrupt

## objectives - teach you to fish - hands-on experience - use version control! - collaborate!

## agenda 1. intro and installation 1. setup and local repositories 1. remote repositories and collaboration note: - we have dynamic breaks, try at most 90 minutes without break

## about version control > records changes what, who, when, why

## 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 today 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

## about christian - scientific computing support @ iDiv since 2014 - happy git user since 2010 > There will never be a better version control system than git. > > -- Christian Krause, 2017

## about dirk - statistics and R support @ iDiv since 2014 - knows that kind of pain: ![blah](img/draft_mess_half_size.png)

## 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/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/gitk-pretty-history.png) notes: - structure - who, when, why

## 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 - (done right) decision based on regression testing

## motivation #3 ![boy scout rule](img/boy-scout-rule.jpg) notes: - there's a rule in ~~open source software~~ nay life - if you want the world to be a better place - complain about it (issue tracker) - if you are able to fix it: do it!

## motivation #3 ### collaboration made easy > This text cntains a typo. notes: - demo GitLab - [go to project](https://git.idiv.de/sc/edu/git-seminar) - check if typo still in master - edit - change **target branch** to create merge request - commit message: ``` fixes typo learn how to use a spell checker, dude! ```

## motivation #4 ### the creative use award #### goes to Michael Schilli ```yml videos: - id: '_3i5yVoTvCs' title: 'How to flip German pancakes' - id: 'brPfE66FC24' title: 'Tivo Stream Cooling Fan Replacement' ``` ```console $ youtube-sync -i videos.yml _3i5yVoTvCs: Unchanged brPfE66FC24: Updated OK ``` source: [Linux Magazin](http://www.linux-magazin.de/) 2018/01

## motivation #e ### use version control for # *everything* | common | less frequent | esoteric? | | ------------ |:---------------:| ---------------:| | software | presentation | youtube | | blog / doc | paper / thesis | soundboard | | user config | task management | drinking games | notes: - software, thats obvious - blog / doc: web-pages in general are more and more managed by git - e.g. this git cheat sheet we're handing out is a git repo - if it doesn't support version control, i.e. text, don't use it, e.g. graphics written in dot, compiled to SVG

## 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 seminar)* 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

## 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 don't use it because it can't use native Windows editors - **cmder**: we've tried it, it sucks

## os packages ### your turn 1. install git CLI 1. open terminal 1. type: `git version`

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

## 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'm using emacs integration (magit) for most of my day-to-day tasks, only a few key presses per git operation, when I'm in the terminal, I simply use the CLI

## 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 ```

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

## git setup #1 ```bash # configure your identity git config --global user.name 'Jane Doe' git config --global user.email 'jane.doe@riot-grrrl.org' # 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 ``` notes: - hand out cheat sheets **now**

## git setup #2 ```bash # command line editor git config --global core.editor nano # Linux GNOME / KDE git config --global core.editor gedit git config --global core.editor kate # Windows git config --global core.editor notepad git config --global core.autocrlf true ``` notes: ### line endings - explain the difference: Windows CRLF, everyone else LF, some accept only LF - maintainers may reject contributions because of line endings - on Windows, git can do it for you, via `dos2unix` - fine grained control with `man 5 gitattributes`

# git command line ## local repositories notes: - add **break** here if needed

## 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: - 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: ```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'll see different outputs

## the staging area ![staging area](img/staging-area.svg) notes: - **don't demo here! that's 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 can't interactively stage/unstage hunks, the UI sucks

## command line ### file handling ```bash # use staging area git stage file git unstage file # discard changes git checkout file # rename and remove git mv source destination git rm file ``` notes: - git stage git add are the same thing - prefer stage and unstage because the opposite of add is remove and that does something entirely different

## command line ### show changes ```bash # from staging area to current working copy git diff # show contents of staging area, i.e. # from last commit to staging area git diff --staged ```

## 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' ```

## 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. - don't 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 ```

## you can now - track changes in your projects - browse your projects history - see why a change was introduced

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

# project licenses ## aka legal shit notes: - 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'll 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 **full clones**, i.e. entire history - **fetch** is on the box, so you **fetch everything** - **fetch** does not integrate branches, i.e. **merge** - **push** and **pull** also **merge** the *tracking* branch

# branch and merge notes: - this is a demo chapter, you'll all do this in collaboration chapter (next one) - what was this **master** again? we haven't 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 - **master** 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

## 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 checkout name ``` notes: ``` # branch, branch --all git lol # show branches # branch wip/feature, lol # checkout 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 checkout master git merge branch-name # delete branch git branch -d branch-name ``` notes: ``` # checkout master, 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 master, lol - group: push origin, lol - group: commit, push, MR (master or wip?) - 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

## view of maintainer ![remotes](img/git-remote-maintainer.svg) notes: - we: review one MR, show line comments in GL, thumbs up

## 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

## 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`

## review ### your turn 1. review a merge request 1. discuss / emote 1. comment on code

## resolving conflicts ### maintainer ```bash git remote add alice https://... git fetch alice git checkout master git merge alice/topic/feature # fix conflicts git push ``` ### contributor ```bash git fetch upstream git checkout topic/feature git merge origin/master # fix conflicts git push ``` notes: - hopefully conflicting changes - MR status should show that (can not be merged without conflicts) - maintainer decides if trivial or delegate to contributor

## you can now - create and connect to remotes - contribute to projects you don't own - maintain projects you own

## 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

EOF

# backup slides

## rebasing ### as maintainer ```bash git remote add alice https://... git fetch alice git rebase [--interactive] master 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/master topic/feature # fix conflicts # force push because branch history changed git push --force ```