<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="author" content="Dirk Sarpe and Christian Krause" />
<title>git basics</title>
<meta name="apple-mobile-web-app-capable" content="yes" />
<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
<link rel="stylesheet" href="reveal.js/css/reveal.css" />
<link rel="stylesheet" href="reveal.js/lib/css/zenburn.css" />
<style type="text/css">code{white-space: pre;}</style>
<link rel="stylesheet" href="reveal.js/css/theme/black.css" id="theme" />
<link rel="stylesheet" href="css/company-logo.css" />
<link rel="stylesheet" href="css/ribbon.css" />
<link rel="stylesheet" href="css/crawl.css" />
</head>
<body>
<div class="reveal">
<div class="slides">
<!---------------------------------------------------------------------
<!-- intro
<!-------------------------------------------------------------------->
<section>
<section id="title" data-markdown>
# 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
</section>
<section id="intro-objectives" data-markdown>
## objectives
- teach you to fish
- hands-on experience
- use version control!
- collaborate!
</section>
<section id="intro-agenda" data-markdown>
## 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
</section>
<section id="intro-version-control" data-markdown>
## about version control
> records changes
what, who, when, why
</section>
<section id="intro-about-git" data-markdown>
## 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
</section>
<section id="intro-about-today" data-markdown>
## 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
</section>
<section id="intro-about-christian" data-markdown>
## 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
</section>
<section id="intro-about-dirk" data-markdown>
## about dirk
- statistics and R support @ iDiv since 2014
- knows that kind of pain:
</section>
<section id="intro-about-you" data-markdown>
## about you
name, job, git experience, why git?
notes:
- re-seat everyone based on command line experience
</section>
</section>
<!---------------------------------------------------------------------
<!-- motivation
<!-------------------------------------------------------------------->
<section>
<section id="motivation" data-markdown>
# 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
</section>
<section id="motivation-avoid-mess" data-markdown>
## motivation #1
### avoid mess
notes:
- who has seen such a mess?
- who has contributed to such a mess?
- who has created such a mess?
</section>
<section id="motivation-want-structure" data-markdown>
## motivation #1
### want structure
notes:
- structure
- who, when, why
</section>
<section id="motivation-playground" data-markdown>
## motivation #2
### throw-away playgrounds
notes:
- test stuff without interfering
- throw away if garbage
- integrate if good
- switch back and forth without pain
</section>
<section id="motivation-collaboration-1" data-markdown>
## motivation #3
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!
</section>
<section id="motivation-collaboration-2" data-markdown>
## motivation #3
### collaboration made easy
<!-- do not fix this typo, it is here on purpose to show collab -->
> 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!
```
</section>
<section id="motivation-collaboration-3" data-markdown>
## motivation #3
notes:
- might not seem like much
- but you are still making the world a better place
- and it is not too much effort
</section>
<section id="motivation-automation" data-markdown>
## 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
</section>
<section class="star-wars" id="motivation-wars">
<div class="crawl">
<div class="title">
<h1>motivation #wars</h1>
</div>
<div data-markdown>
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?
</div>
<img src="http://i.giphy.com/90F8aUepslB84.gif" />
</div>
</section>
</section>
<!---------------------------------------------------------------------
<!-- install and setup
<!-------------------------------------------------------------------->
<section>
<section id="install" data-markdown>
# install
</section>
<section id="setup-cli" data-markdown>
## command line
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
</section>
<section id="install-os-packages" data-markdown>
## 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
</section>
<section id="install-your-turn" data-markdown>
## 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`
</section>
</section>
<section>
<section id="setup" data-markdown>
# setup
notes:
- add **break** here if needed
</section>
<section id="cli-description" data-markdown>
## 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
</section>
<section id="cli-bash-basics" data-markdown>
## 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 `..`
</section>
<section id="cli-git" data-markdown>
## command line
### git syntax
```bash
# every git command
git command [arguments]
# get help
git help [command]
```
</section>
<section id="setup-git-1" data-markdown>
## 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
</section>
<section id="setup-git-2" data-markdown>
## 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
</section>
</section>
<!---------------------------------------------------------------------
<!-- basic command line usage
<!-------------------------------------------------------------------->
<section>
<section id="cli-basic" data-markdown>
# git command line
## local repositories
notes:
- add **break** here if needed
- this section has demo and interactive part
</section>
<section id="cli-create-repository" data-markdown>
## 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
</section>
<section id="cli-create-repository-your-turn" data-markdown>
## 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
```
</section>
<section id="cli-git-status" data-markdown>
## 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
</section>
<section id="internals-staging-area" data-markdown>
## the staging area
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
</section>
<section id="cli-git-files" data-markdown>
## 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
</section>
<section id="cli-git-diff-1" data-markdown>
## 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
</section>
<section id="cli-git-commit" data-markdown>
## 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
</section>
<section id="commit-messages-xkcd" data-markdown>
## commit messages
</section>
<section id="commit-messages-example" data-markdown>
## 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`
</section>
<section id="cli-git-log" data-markdown>
## 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
</section>
<section id="summary-1" data-markdown>
## you can now
- track changes in your projects
- browse your projects history
- see why a change was introduced
</section>
<section id="summary-2" data-markdown>
## goals
1. use git in **ALL** your projects ✓
2. collaborate with each other
</section>
</section>
<!---------------------------------------------------------------------
<!-- licenses
<!-------------------------------------------------------------------->
<section>
<section id="licenses" data-markdown>
# 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
</section>
<section id="licenses-none" data-markdown>
## no license
- exclusive copyright to **each!** author
- **no one** can use, copy, distribute or modify
</section>
<section id="licenses-software" data-markdown>
## software licenses
notes:
- there are closed source licenses as well, ask your legal department about those
</section>
<section id="licenses-other" data-markdown>
## other licenses
- media, documentation: creative commons
- paper / thesis: journal vs legal department
</section>
<section id="licenses-choose" data-markdown>
## guide
https://choosealicense.com
</section>
</section>
<!---------------------------------------------------------------------
<!-- distributed
<!-------------------------------------------------------------------->
<section>
<section id="distributed" data-markdown>
# distributed
## version control system
notes:
- add **break** here if needed
</section>
<section id="distributed-local" data-markdown>
## 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
</section>
<section id="distributed-webapps" data-markdown>
### how do i get remotes?
# web apps
- GitLab demo
- GitHub (no demo)
notes:
- log in
- create project
- push / pull
</section>
<section id="distributed-remotes" data-markdown>
## 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
</section>
<section id="distributed-remote-interaction" data-markdown>
## remote
### interaction
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
</section>
</section>
<!---------------------------------------------------------------------
<!-- branch and merge
<!-------------------------------------------------------------------->
<section>
<section id="branch-merge" data-markdown>
# 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
</section>
<section id="branch-visual" data-markdown>
## branches visualized
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
</section>
<section id="branch-when-to-use" data-markdown>
## when to use branches
- breaking **master**
- something takes longer
- frequent interruptions
- comment out code
notes:
- if logical commit without breaking do not branch
</section>
<section id="branch-commands" data-markdown>
## 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
</section>
<section id="branch-names" data-markdown>
## 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`
</section>
<section id="branch-merging" data-markdown>
## 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
```
</section>
</section>
<!---------------------------------------------------------------------
<!-- collaboration
<!-------------------------------------------------------------------->
<section>
<section id="collab" data-markdown>
# collaboration
notes:
- add **break** here if needed
- we: create new repo
- group: fork and clone, remote add upstream, lol
- next slide, explain img
</section>
<section id="collab-contributor" data-markdown>
## view of contributor
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
</section>
<section id="collab-maintainer" data-markdown>
## view of maintainer
notes:
- we: review one MR, show line comments in GL, thumbs up
</section>
<section id="collab-review-criticism" data-markdown>
## 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
</section>
<section id="collab-review-code-of-conduct" data-markdown>
## 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`
</section>
<section id="collab-review-your-turn" data-markdown>
## review
### your turn
1. review a merge request
1. discuss / emote
1. comment on code
</section>
<section id="collab-conflicts" data-markdown>
## 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
</section>
<section id="summary-3" data-markdown>
## you can now
- create and connect to remotes
- contribute to projects you do not own
- maintain projects you own
</section>
<section id="summary-4" data-markdown>
## goals
1. use git in **ALL** your projects ✓
2. collaborate with each other ✓
</section>
</section>
<section>
<section id="homework" data-markdown>
# homework
</section>
<section id="homework-use-git" data-markdown>
## 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
</section>
<section id="homework-collaborate" data-markdown>
## 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
</section>
<section id="homework-feedback" data-markdown>
## homework #3
### feedback
https://git.idiv.de/sc/edu/git-seminar
notes:
- remember code of conduct, criticism and commenting rules
</section>
</section>
<section id="eof" data-background="img/trex.png">
<h1>EOF</h1>
</section>
<section>
<section id="backup" data-markdown>
# backup slides
</section>
<section id="collab-rebase-maintainer" data-markdown>
## 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
</section>
<section id="collab-rebase-contributor" data-markdown>
## rebasing
### as contributor
```bash
git fetch upstream
git rebase origin/master topic/feature
# fix conflicts
# force push because branch history changed
git push --force
```
</section>
</section>
</div>
</div>
<!-- company logo -->
<div class="logo-wrapper">
<a href="https://www.idiv.de/">
<img src="img/company-logo-small.png" />
</a>
</div>
<!-- ribbon -->
<div class="ribbon-wrapper right">
<div class="ribbon">
<a href="https://git.idiv.de/sc/edu/git-seminar">
edit
</a>
</div>
</div>
<!-- reveal.stuff -->
<script src="reveal.js/lib/js/head.min.js"></script>
<script src="reveal.js/js/reveal.js"></script>
<script>
Reveal.initialize({
controls: true,
progress: true,
slideNumber: true,
history: true,
center: true,
keyboard: true,
maxScale: 1.5,
slideNumber: false,
theme: Reveal.getQueryHash().theme,
transition: Reveal.getQueryHash().transition || 'default',
dependencies: [
{ src: 'reveal.js/lib/js/classList.js', condition: function() { return !document.body.classList; } },
{ src: 'reveal.js/plugin/zoom-js/zoom.js', async: true, condition: function() { return !!document.body.classList; } },
{ src: 'reveal.js/plugin/notes/notes.js', async: true, condition: function() { return !!document.body.classList; } },
{ src: 'reveal.js/plugin/markdown/marked.js', condition: function() { return !!document.querySelector( '[data-markdown]' ); } },
{ src: 'reveal.js/plugin/markdown/markdown.js', condition: function() { return !!document.querySelector( '[data-markdown]' ); } },
{ src: 'reveal.js/plugin/highlight/highlight.js', async: true, callback: function() { hljs.initHighlightingOnLoad(); } },
]
});
</script>
</body>
</html>