# 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:
## about you
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
notes:
- who has seen such a mess?
- who has contributed to such a mess?
- who has created such a mess?
## motivation #1
### want structure
notes:
- TODO better repo with more contributors
- structure
- who, when, why
## motivation #2
### throw-away playgrounds
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
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 cuntains 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
## os packages
- **Linux:** `bash` and `git`
- **Mac:** `bash` and `git`
- **Windows 10+:** `WSL`
- **Windows < 10:** `cmder`
notes:
- [Windows Subsystem for Linux](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux)
- who needs install? others can go instant break
# break
notes:
- keep break short, only for installation
- hand out cheat sheets
## command line
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
### 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
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
## 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
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
## 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
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
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
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 #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
## rebasing
### maintainer
```bash
git remote add alice https://...
git fetch alice
git rebase master alice/topic/feature
# fix conflicts
git push
# close merge request
```
### contributor
```bash
git fetch upstream
git rebase origin/master topic/feature
# fix conflicts
# force push because branch history changed
git push --force
```
notes:
- manually close merge request because no merge commit
