# git basics ## for beginner-level git users notes: - 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

## 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 be able to ... 1. use git in **ALL** your projects 2. 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 so that experienced user sits together with inexperienced user

# motivation > Why should I use git?

## 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: - TODO better repo with more contributors - 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 contains 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 of git 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 git don't use it

## motivation #a ### automation - software testing - code quality - deploy to app store - deploy presentation on web server *(see advanced seminar)* notes: - 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) --- 1. install 1. open terminal 1. type: `git version` 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

# break notes: - keep break short, only for installation - hand out cheat sheets

# setup

## command line ![staging area](img/matrix-pill.jpg) notes: - learn by doing / understand what you do - gui hides too much of that - use gui if gui helps workflow

## 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' ``` notes: - open a terminal

## git setup #2 ```bash # editor git config --global core.editor emacs # WINDOWS ONLY: let git handle line endings git config --global core.autocrlf true ``` notes: - talk about line endings - maintainers may reject contributions because of line endings - difference between git config and editor config - you can have fine grained control over this with gitattributes(5)

# git command line ## local repositories

## 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 - mkdir ~/projects - git init hello - README.md - src/hello.lang - for #homework you init your existing projects *without* version control

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

## internals ### the staging area ![staging area](img/staging-area.svg) notes: - can I have your attention, please? - content can be in three stages - we make changes, these are not yet known to git - we prepare a commit by **successively** adding changes to the staging area - we commit this **set of changes** - a commit **should be a logical unit** of changes

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

## 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 - show when and why which changes were made

## you can now > use git in **ALL** your projects > > -- goal 1 finished ✓

# project licenses ## aka legal shit notes: - 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

# break

# distributed ## version control system

## 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: my `~/projects` does not need to be backed up because **every** project is under version control and has a remote

## remotes ![remotes](img/git-remote-solo.svg) notes: - remotes have names, default to origin - remotes are clones

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

# branch and merge notes: - what was this **master** again?

## branches ```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: - use wip/feature as branch name, see motivation playground - use git lol frequently to showcase its importance - make changes in playground - git push - make changes in master - git lol - make changes in playground

## branch naming ### conventions - dashes in names - slashes for categories ```markdown topic/ui/input-form wip/test-different-fonts hotfix/42 release/1.6.0 ``` 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: - use git lol to show final layout

# collaboration notes: - 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

## review code of conduct: - be friendly - be responsible - be open - be creative - be proactive - have fun

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

# homework

## homework #1 ### use git for each project you use ... ... create repository in GitLab ... ... and commit 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

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