Forked from
Scientific Computing / education / git-seminar
79 commits behind the upstream repository.
Code owners
Assign users and groups as approvers for specific file changes. Learn more.
basics.html 33.42 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:
- terminal session preparation:
- two terminals each with same tmux session, check font size
- remove user, host and path from prompt
- clean git config for demo
- 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
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
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 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:
- 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 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 version control, i.e. text, don't use it,
e.g. graphics written in dot, compiled to SVG
</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="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 don't use it because it
can't use native Windows editors
- **cmder**: we've 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`
</section>
</section>
<section>
<section id="setup" data-markdown>
# setup
notes: - add **break** here if needed
</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'm using emacs integration (magit)
for most of my day-to-day tasks, only a few key presses per git
operation, when I'm in the terminal, I simply use the CLI
</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'
# show config
git config --list
```
notes:
- hand out cheat sheets **now**
</section>
<section id="setup-git-2" data-markdown>
## git setup #2
```bash
# command line editor
git config --global core.editor nano
# Linux GNOME / KDE
git config --global core.editor gedit
git config --global core.editor kate
# Windows
git config --global core.editor notepad
git config --global core.autocrlf true
```
notes:
### line endings
- explain the difference: Windows CRLF, everyone else LF, some
accept only LF
- maintainers may reject contributions because of line endings
- on Windows, git can do it for you, via `dos2unix`
- fine grained control with `man 5 gitattributes`
</section>
</section>
<!---------------------------------------------------------------------
<!-- basic command line usage
<!-------------------------------------------------------------------->
<section>
<section id="cli-basic" data-markdown>
# git command line
## local repositories
notes:
- add **break** here if needed
</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>
## the staging area
notes:
- **don't demo here! that's 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 can't 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 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 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.
- 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
- 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
```
</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>
## 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:
- 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'll 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'll all do this in collaboration
chapter (next one)
- what was this **master** again? we haven't 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-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 checkout name
```
notes:
```
# branch, branch --all
git lol # show branches
# branch wip/feature, lol
# checkout 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 checkout master
git merge branch-name
# delete branch
git branch -d branch-name
```
notes:
```
# checkout 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: 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-coc" 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
- decide with your team, 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 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>