Skip to content
Snippets Groups Projects
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:

            ![blah](img/draft_mess_half_size.png)
          </section>

          <section id="intro-about-you" data-markdown>
            ## about you

            ![people](img/people.jpg)

            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

            ![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?
          </section>

          <section id="motivation-want-structure" data-markdown>
            ## motivation #1
            ### want structure

            ![blah](img/gitk-pretty-history.png)

            notes:
            - TODO better repo with more contributors
            - structure
            - who, when, why
          </section>

          <section id="motivation-playground" data-markdown>
            ## 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
          </section>

          <section id="motivation-collaboration-1" data-markdown>
            ## motivation #3

            ![boy scout rule](img/boy-scout-rule.jpg)

            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

            ![staging area](img/matrix-pill.jpg)

            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

            ![staging area](img/staging-area.svg)

            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
            ![software licenses](img/xkcd-1296-git-commit.png)
          </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

            ![software licenses](img/license-chooser.svg)

            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

            ![remotes](img/git-remote-solo.svg)

            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

            ![remotes](img/git-remote-contributor.svg)

            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

            ![remotes](img/git-remote-maintainer.svg)

            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>