-
Dirk Sarpe authoredDirk Sarpe authored
Code owners
Assign users and groups as approvers for specific file changes. Learn more.
basics.html 29.35 KiB
<!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:
- close your laptops
- hand out cheat sheets later, no need to write stuff down
- 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
</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
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
</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 so that experienced user sits together with
inexperienced user
</section>
</section>
<!---------------------------------------------------------------------
<!-- motivation
<!-------------------------------------------------------------------->
<section>
<section id="motivation" data-markdown>
# motivation
> Why should I use git?
</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:
- TODO better repo with more contributors
- 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
- (done right) decision based on regression testing
</section>
<section id="motivation-collaboration-1" data-markdown>
## 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!
</section>
<section id="motivation-collaboration-2" data-markdown>
## motivation #3
### collaboration made easy
<!-- do not fix this typo, it's 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-creative-use" data-markdown>
## 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
</section>
<section id="motivation-use-everywhere" data-markdown>
## 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
</section>
<section id="motivation-automation" data-markdown>
## 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
</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-os-packages" data-markdown>
## 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
</section>
</section>
<section id="break-1" data-markdown>
# break
notes:
- keep break short, only for installation
- hand out cheat sheets
</section>
<section>
<section id="setup" data-markdown>
# setup
</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 if gui helps workflow
</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
```
</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'
```
notes:
- open a terminal
</section>
<section id="setup-git-2" data-markdown>
## 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)
</section>
</section>
<!---------------------------------------------------------------------
<!-- basic command line usage
<!-------------------------------------------------------------------->
<section>
<section id="cli-basic" data-markdown>
# git command line
## local repositories
</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:
- 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
</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'll see different outputs
</section>
<section id="internals-staging-area" data-markdown>
## 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
</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 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
</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
```
</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'
```
</section>
<section id="commit-messages-xkcd" data-markdown>
## commit messages

</section>
<section id="commit-messages-example" data-markdown>
## 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
</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
```
</section>
<section id="summary-1" data-markdown>
## you can now
- track changes in your projects
- browse your projects history
- show when and why which changes were made
</section>
<section id="summary-2" data-markdown>
## you can now
> use git in **ALL** your projects
>
> -- goal 1 finished ✓
</section>
</section>
<!---------------------------------------------------------------------
<!-- licenses
<!-------------------------------------------------------------------->
<section>
<section id="licenses" data-markdown>
# 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
</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>
<section id="break-2" data-markdown>
# break
</section>
<!---------------------------------------------------------------------
<!-- distributed
<!-------------------------------------------------------------------->
<section>
<section id="distributed" data-markdown>
# distributed
## version control system
</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: my `~/projects` does not need to
be backed up because **every** project is under version control
and has a remote
</section>
<section id="distributed-remotes" data-markdown>
## remotes

notes:
- remotes have names, default to origin
- remotes are clones
</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>
<!---------------------------------------------------------------------
<!-- branch and merge
<!-------------------------------------------------------------------->
<section>
<section id="branch-merge" data-markdown>
# branch and merge
notes:
- what was this **master** again?
</section>
<section id="branches" data-markdown>
## 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
</section>
<section id="branch-names" data-markdown>
## 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
</section>
<section id="merging" data-markdown>
## 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
</section>
</section>
<!---------------------------------------------------------------------
<!-- collaboration
<!-------------------------------------------------------------------->
<section>
<section id="collab" data-markdown>
# collaboration
notes:
- 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: 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
</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" data-markdown>
## review
code of conduct:
- be friendly
- be responsible
- be open
- be creative
- be proactive
- have fun
</section>
<section id="collab-conflicts" data-markdown>
## 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
</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 ...
... 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
</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
</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>