# git basics ## for beginner-level git users notes: - `make -B` to create images - two terminals each with same tmux session, increase font size - `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
## 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 is 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 #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 #e ### use version control for # *everything* - software - blog / documentation - presentation - paper / thesis - ... notes: - software, thats obvious - blog / doc: web-pages in general are more and more managed by git - e.g. this git cheat sheet we are handing out is a git repo - if it does not support version control, i.e. text, do not 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
## 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] ```
## 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 --global --list ``` 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 ``` 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 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 ``` 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 - 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: - 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 **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 will all do this in collaboration chapter (next one) - what was this **master** 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 - **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
## when to use branches - breaking **master** - something takes longer - frequent interruptions - 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 master git merge branch-name # delete branch git branch -d branch-name ``` notes: ``` # switch 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: 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
## 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 switch master git merge alice/topic/feature # fix conflicts git push ``` ### contributor ```bash git fetch upstream git switch 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 do not 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 ```
edit