Skip to content
Snippets Groups Projects

Compare revisions

Changes are shown as if the source revision was being merged into the target revision. Learn more about comparing revisions.

Source

Select target project
No results found
Select Git revision
  • krausec-main-patch-16624
  • main
  • fixes-typo-2025-04-14
  • fixes-typo-2025-03-27
  • fixes-typo-2025u
  • fixes-typo-19
  • fixes-typo-9
  • fixes-typo-8
  • wip/project-management
  • wip/config-paste
  • lfs
11 results

Target

Select target project
No results found
Select Git revision
  • fix/typo
  • master
  • wip/project-management
  • lfs
4 results
Show changes

Commits on Source 72

34 files
+ 1563
− 773
Compare changes
  • Side-by-side
  • Inline

Files

.gitignore

+10 −0
Original line number Original line Diff line number Diff line
@@ -2,5 +2,15 @@ img/git-remote-contributor.svg 
img/git-remote-maintainer.svg

img/git-remote-maintainer.svg

img/git-remote-solo.svg

img/git-remote-solo.svg

img/license-chooser.svg

img/license-chooser.svg

img/motivation-structure.svg

img/motivation-throwaway-playground.svg

img/motivation-throwaway-playground.svg

img/rdm-use-case-data.svg

img/rdm-use-cases-a.svg

img/rdm-use-cases-b.svg

img/rdm-use-cases.svg

img/staging-area.svg

img/staging-area.svg

paper.html

paper.pdf

*.pdf

img/staging-area-diff.svg

/img/rdm-use-case-merged.svg

.gitmodules

+3 −0
Original line number Original line Diff line number Diff line 
[submodule "reveal.js"]

[submodule "reveal.js"]

	path = reveal.js

	path = reveal.js

	url = https://github.com/hakimel/reveal.js.git

	url = https://github.com/hakimel/reveal.js.git

[submodule "pandoc-cheat-sheet"]

	path = pandoc-cheat-sheet

	url = https://github.com/idiv-biodiversity/pandoc-cheat-sheet.git

Makefile

+23 −0
Original line number Original line Diff line number Diff line
@@ -4,12 +4,35 @@ SUBDIRS = \ 
$(SUBDIRS):

$(SUBDIRS):

	$(MAKE) -C $@

	$(MAKE) -C $@





pandoc-papers.pdf: pandoc-papers.md

	pandoc \

		-V aspectratio=169 \

		-V institute=iDiv \

		-V theme=Frankfurt \

		-V navigation=horizontal \

		-V logo=img/idiv-black-logo.png \

		--pdf-engine=xelatex \

		-s \

		-t beamer \

		-o pandoc-papers.pdf \

		pandoc-papers.md



rdm.pdf: img rdm.md rdm.yml

	pandoc \

		--standalone \

		--from=markdown+yaml_metadata_block \

		--pdf-engine=xelatex \

		--template=pandoc-cheat-sheet/cheat-sheet.tex \

		-o rdm.pdf \

		rdm.yml rdm.md



all: subdirs

all: subdirs





clean:

clean:

	for dir in $(SUBDIRS); do \

	for dir in $(SUBDIRS); do \

	  $(MAKE) -C $$dir $@; \

	  $(MAKE) -C $$dir $@; \

	done

	done

	rm -f rdm.pdf





default: all

default: all

advanced.md

0 → 100644
+38 −0
Original line number Original line Diff line number Diff line 
# regular FAQ



- 10-12 git integration RStudio / VS Code / others

- 13-15 GitLab / GitHub project setup / importing existing projects / how to start and continue after that, project management, issue management

- 15-16 GitLab / GitHub automation

- 16-18 free for all



# git advanced -- how to maintain a comprehensible history



- when projects get bigger

- show bad example with merge commits

- show git-flow being harmful

- show git-pretty



Advanced git is not about edge use cases, it's all about keeping your history

comprehensible, i.e. understandable.



## trunk based development



- project history, e.g. via `gitk` or `git lol`, should resemble a **tree**

- for this section we're sticking to the tree metaphor

- long-lived branches basically **master** (and **releases**)

- long trunk of tree

- dead branches on lower trunk (old, unmaintained releases), which may also be

  cut down in time if support is dropped

- only clean merges (could have been ff)



## final chapter



- consider like backup slides

- show goodies



## resources



- https://barro.github.io/2016/02/a-succesful-git-branching-model-considered-harmful/

- https://stackoverflow.com/questions/14023648/why-does-my-git-history-look-like-a-christmas-tree

- https://i.stack.imgur.com/ZsXT6.png

- https://trunkbaseddevelopment.com

basics.html

+299 −258

File changed.

Preview size limit exceeded, changes collapsed.

dia/rebase-vs-cherry-pick.dia

+17 −17
Original line number Original line Diff line number Diff line
@@ -100,7 +100,7 @@ 
            <dia:real val="0.80000000000000004"/>

            <dia:real val="0.80000000000000004"/>

          </dia:attribute>

          </dia:attribute>

          <dia:attribute name="pos">

          <dia:attribute name="pos">

            <dia:point val="30,18.6171"/>

            <dia:point val="30,18.6161"/>

          </dia:attribute>

          </dia:attribute>

          <dia:attribute name="color">

          <dia:attribute name="color">

            <dia:color val="#000000"/>

            <dia:color val="#000000"/>
@@ -194,7 +194,7 @@ 
        <dia:point val="33,15"/>

        <dia:point val="33,15"/>

      </dia:attribute>

      </dia:attribute>

      <dia:attribute name="obj_bb">

      <dia:attribute name="obj_bb">

        <dia:rectangle val="32.8075,14.2525;33.1925,15"/>

        <dia:rectangle val="32.8075,14.255;33.1925,15"/>

      </dia:attribute>

      </dia:attribute>

      <dia:attribute name="text">

      <dia:attribute name="text">

        <dia:composite type="text">

        <dia:composite type="text">
@@ -208,7 +208,7 @@ 
            <dia:real val="0.80000000000000004"/>

            <dia:real val="0.80000000000000004"/>

          </dia:attribute>

          </dia:attribute>

          <dia:attribute name="pos">

          <dia:attribute name="pos">

            <dia:point val="33,14.8475"/>

            <dia:point val="33,14.8491"/>

          </dia:attribute>

          </dia:attribute>

          <dia:attribute name="color">

          <dia:attribute name="color">

            <dia:color val="#000000"/>

            <dia:color val="#000000"/>
@@ -227,7 +227,7 @@ 
        <dia:point val="38,15"/>

        <dia:point val="38,15"/>

      </dia:attribute>

      </dia:attribute>

      <dia:attribute name="obj_bb">

      <dia:attribute name="obj_bb">

        <dia:rectangle val="37.8075,14.2525;38.1925,15"/>

        <dia:rectangle val="37.8075,14.255;38.1925,15"/>

      </dia:attribute>

      </dia:attribute>

      <dia:attribute name="text">

      <dia:attribute name="text">

        <dia:composite type="text">

        <dia:composite type="text">
@@ -241,7 +241,7 @@ 
            <dia:real val="0.80000000000000004"/>

            <dia:real val="0.80000000000000004"/>

          </dia:attribute>

          </dia:attribute>

          <dia:attribute name="pos">

          <dia:attribute name="pos">

            <dia:point val="38,14.8475"/>

            <dia:point val="38,14.8491"/>

          </dia:attribute>

          </dia:attribute>

          <dia:attribute name="color">

          <dia:attribute name="color">

            <dia:color val="#000000"/>

            <dia:color val="#000000"/>
@@ -290,7 +290,7 @@ 
        <dia:point val="33,5"/>

        <dia:point val="33,5"/>

      </dia:attribute>

      </dia:attribute>

      <dia:attribute name="obj_bb">

      <dia:attribute name="obj_bb">

        <dia:rectangle val="30.8137,4.38631;35.2049,6.78988"/>

        <dia:rectangle val="30.8137,4.40594;35.1863,6.75094"/>

      </dia:attribute>

      </dia:attribute>

      <dia:attribute name="text">

      <dia:attribute name="text">

        <dia:composite type="text">

        <dia:composite type="text">
@@ -343,7 +343,7 @@ git rebase b c#</dia:string> 
        <dia:point val="28,11"/>

        <dia:point val="28,11"/>

      </dia:attribute>

      </dia:attribute>

      <dia:attribute name="obj_bb">

      <dia:attribute name="obj_bb">

        <dia:rectangle val="27.8075,10.2525;28.1925,11"/>

        <dia:rectangle val="27.8075,10.255;28.1925,11"/>

      </dia:attribute>

      </dia:attribute>

      <dia:attribute name="text">

      <dia:attribute name="text">

        <dia:composite type="text">

        <dia:composite type="text">
@@ -357,7 +357,7 @@ git rebase b c#</dia:string> 
            <dia:real val="0.80000000000000004"/>

            <dia:real val="0.80000000000000004"/>

          </dia:attribute>

          </dia:attribute>

          <dia:attribute name="pos">

          <dia:attribute name="pos">

            <dia:point val="28,10.8475"/>

            <dia:point val="28,10.8491"/>

          </dia:attribute>

          </dia:attribute>

          <dia:attribute name="color">

          <dia:attribute name="color">

            <dia:color val="#000000"/>

            <dia:color val="#000000"/>
@@ -408,7 +408,7 @@ git rebase b c#</dia:string> 
            <dia:real val="0.80000000000000004"/>

            <dia:real val="0.80000000000000004"/>

          </dia:attribute>

          </dia:attribute>

          <dia:attribute name="pos">

          <dia:attribute name="pos">

            <dia:point val="51,12.195"/>

            <dia:point val="51,12.1941"/>

          </dia:attribute>

          </dia:attribute>

          <dia:attribute name="color">

          <dia:attribute name="color">

            <dia:color val="#000000"/>

            <dia:color val="#000000"/>
@@ -502,7 +502,7 @@ git rebase b c#</dia:string> 
        <dia:point val="56,15"/>

        <dia:point val="56,15"/>

      </dia:attribute>

      </dia:attribute>

      <dia:attribute name="obj_bb">

      <dia:attribute name="obj_bb">

        <dia:rectangle val="55.8075,14.2525;56.1925,15"/>

        <dia:rectangle val="55.8075,14.255;56.1925,15"/>

      </dia:attribute>

      </dia:attribute>

      <dia:attribute name="text">

      <dia:attribute name="text">

        <dia:composite type="text">

        <dia:composite type="text">
@@ -516,7 +516,7 @@ git rebase b c#</dia:string> 
            <dia:real val="0.80000000000000004"/>

            <dia:real val="0.80000000000000004"/>

          </dia:attribute>

          </dia:attribute>

          <dia:attribute name="pos">

          <dia:attribute name="pos">

            <dia:point val="56,14.8475"/>

            <dia:point val="56,14.8491"/>

          </dia:attribute>

          </dia:attribute>

          <dia:attribute name="color">

          <dia:attribute name="color">

            <dia:color val="#000000"/>

            <dia:color val="#000000"/>
@@ -535,7 +535,7 @@ git rebase b c#</dia:string> 
        <dia:point val="61,15"/>

        <dia:point val="61,15"/>

      </dia:attribute>

      </dia:attribute>

      <dia:attribute name="obj_bb">

      <dia:attribute name="obj_bb">

        <dia:rectangle val="60.8075,14.2525;61.1925,15"/>

        <dia:rectangle val="60.8075,14.255;61.1925,15"/>

      </dia:attribute>

      </dia:attribute>

      <dia:attribute name="text">

      <dia:attribute name="text">

        <dia:composite type="text">

        <dia:composite type="text">
@@ -549,7 +549,7 @@ git rebase b c#</dia:string> 
            <dia:real val="0.80000000000000004"/>

            <dia:real val="0.80000000000000004"/>

          </dia:attribute>

          </dia:attribute>

          <dia:attribute name="pos">

          <dia:attribute name="pos">

            <dia:point val="61,14.8475"/>

            <dia:point val="61,14.8491"/>

          </dia:attribute>

          </dia:attribute>

          <dia:attribute name="color">

          <dia:attribute name="color">

            <dia:color val="#000000"/>

            <dia:color val="#000000"/>
@@ -598,14 +598,14 @@ git rebase b c#</dia:string> 
        <dia:point val="56,5"/>

        <dia:point val="56,5"/>

      </dia:attribute>

      </dia:attribute>

      <dia:attribute name="obj_bb">

      <dia:attribute name="obj_bb">

        <dia:rectangle val="52.9162,4.38631;59.1024,7.58988"/>

        <dia:rectangle val="52.9175,4.38731;59.1011,7.58819"/>

      </dia:attribute>

      </dia:attribute>

      <dia:attribute name="text">

      <dia:attribute name="text">

        <dia:composite type="text">

        <dia:composite type="text">

          <dia:attribute name="string">

          <dia:attribute name="string">

            <dia:string>#cherry-pick

            <dia:string>#cherry-pick





git checkout b

git switch b

git cherry-pick a...c#</dia:string>

git cherry-pick a...c#</dia:string>

          </dia:attribute>

          </dia:attribute>

          <dia:attribute name="font">

          <dia:attribute name="font">
@@ -652,7 +652,7 @@ git cherry-pick a...c#</dia:string> 
        <dia:point val="51,11"/>

        <dia:point val="51,11"/>

      </dia:attribute>

      </dia:attribute>

      <dia:attribute name="obj_bb">

      <dia:attribute name="obj_bb">

        <dia:rectangle val="50.8075,10.2525;51.1925,11"/>

        <dia:rectangle val="50.8075,10.255;51.1925,11"/>

      </dia:attribute>

      </dia:attribute>

      <dia:attribute name="text">

      <dia:attribute name="text">

        <dia:composite type="text">

        <dia:composite type="text">
@@ -666,7 +666,7 @@ git cherry-pick a...c#</dia:string> 
            <dia:real val="0.80000000000000004"/>

            <dia:real val="0.80000000000000004"/>

          </dia:attribute>

          </dia:attribute>

          <dia:attribute name="pos">

          <dia:attribute name="pos">

            <dia:point val="51,10.8475"/>

            <dia:point val="51,10.8491"/>

          </dia:attribute>

          </dia:attribute>

          <dia:attribute name="color">

          <dia:attribute name="color">

            <dia:color val="#000000"/>

            <dia:color val="#000000"/>

git-course.html

deleted100644 → 0
+0 −350
Original line number Original line Diff line number Diff line 
<!DOCTYPE html>

<html>

  <head>

    <meta charset="utf-8">

    <meta name="author" content="Christian Krause" />

    <meta name="dcterms.date" content="2015-06-15" />

    <title>Git Workshop</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"/>

    <style type="text/css">code{white-space: pre;}</style>

    <link rel="stylesheet" href="reveal.js/css/theme/black.css" id="theme" />



    <!-- If the query includes 'print-pdf', include the PDF print sheet -->

    <script>

      if( window.location.search.match( /print-pdf/gi ) ) {

        var link = document.createElement( 'link' );

        link.rel = 'stylesheet';

        link.type = 'text/css';

        link.href = 'reveal.js/css/print/pdf.css';

        document.getElementsByTagName( 'head' )[0].appendChild( link );

      }

    </script>



    <!--[if lt IE 9]>

    <script src="reveal.js/lib/js/html5shiv.js"></script>

    <![endif]-->

  </head>



  <body>

    <div class="reveal">

      <div class="slides">



        <section>

          <h1 class="title">Git Workshop</h1>

          <h3 class="author">Dirk Sarpe & Christian Krause</h3>



          <aside class="notes">

            <ul>

              <li>if you have questions ask them right away</li>

            </ul>

          </aside>

        </section>



        <section id="poll-why-are-you-here" class="titleslide slide level1" data-markdown>

          ## Poll

          # Why are you here?



          Note:

          - Someone (like us) told you it ~~might be~~ **is** useful.

          - You never took the time to really learn it.

          - You already know and use it, want to show off / learn new tricks.



          - Somebody forced you to come here.

          - You wanted to get away from your desk for once and maybe take a nap.

        </section>



        <section id="outline" class="titleslide slide level1" data-markdown>

          # Outline



          1. Intro

          2. Git Commands

          3. GitLab / GitHub

          4. Workflows



          Note:

          - jeder Block ~ 1.5h

          - insgesamt 2h mit Pause

          - 8h - ein ganzer Tag git

          - ein-satz-beschreibungen zu den abschnitten

            - 0. why vcs, why git, getting started with git

            - 1. git basics

            - 2. web collaboration tools

            - 3. how to collaborate in organized manner

        </section>



        <section>

          <section class="titleslide slide level1" data-markdown>

            ## Block 1

            # Introduction



            Note:

            - quickly talk about block outline

              - why vcs? why git?

              - installation git client

              - setup GitLab / GitHub accounts

              - getting started with git (try git)

          </section>



          <section class="slide level2" data-markdown>

            ### Have you ever seen this?



            ![foo](img/draft_mess.png)



            Note:

            - Dirk erklärt seine mess

            - wouldn't it be nicer to have

          </section>



          <section class="slide level2" data-markdown>

            ### wouldn't it be nicer to have

            # version control



            ```

            Dirk Sarpe         14 minutes ago   fix reference

            Dirk Sarpe         5 days ago       adapt figures to nature

            Christian Krause   6 days ago       add figure captions

            Dirk Sarpe         7 weeks ago      adds mean values to analysis

            Christian Krause   7 weeks ago      adds abstract

            ```



            Note:

            - git log --pretty=format'%an %ar %s'

            - and as you can see not only for source code

          </section>



          <section class="slide level2" data-markdown>

            ## have you ever ...



            - review history (see diff)

            - wanted to go back in time

            - maintain multiple versions

              - hint: for different journals

              - try things out without breaking what works



            Note:

            - 

          </section>



          <section class="slide level2" data-markdown>

            ## have you ever ...



            - collaborate

            - who made that error

            - see project progress

            - lost code (no backup)



            Note:

            - 

          </section>



          <section class="slide level2" data-markdown>

            # yes?



            Note:

            - 

          </section>



          <section class="slide level2" data-markdown>

            # use vcs!



            Note:

            - 

          </section>

        </section>



        <section>

          <section class="titleslide slide level1" data-markdown>

            ## Block 1

            # git



            Note:

            - 

          </section>



          <section class="titleslide slide level1" data-markdown>

            ![git](img/what-is-git.jpg)



            Note:

            - 

          </section>



          <section class="titleslide slide level1" data-markdown>

            ![git](img/what-is-git-answer.jpg)



            Note:

            - 

          </section>



          <section class="titleslide slide level1" data-markdown>

            ![git](img/say-what.jpg)



            Note:

            - 

          </section>



          <section class="titleslide slide level1" data-markdown>

            ## what is git? (2nd try)

            ### seriously



            # TODO image gitk all, visual representation of git parent child tree with remotes,

            tags, good commit messages, etc. mit local change der remote noch nicht da ist



            Note:

            - am bild dvcs erklären!

          </section>



          <section class="slide level2" data-markdown>

            ![git](img/idontalwaysusevcs.jpg)



            Note:

            - 

          </section>



          <section class="slide level2" data-markdown>

            ## Why do we all use git?



            #### non-technical



            - any workflow

            - collaboration

            - experimentation

            - undo mistakes

            - state of the art (best tool for the job)

            - all the cool kids do it



            Note:

            - 

          </section>



          <section class="slide level2" data-markdown>

            ## Why do we all use git?



            #### technical



            - never lose data (not just remote but also file integrity)

            - easy conflict resolution

            - local (your own copy of everything)

            - implies speedy gonzales



            Note:

            - 

          </section>

        </section>

      </section>



      <section>

        <section id="prereq" class="titleslide slide level1" data-markdown>

          ### Block 1

          ## Git Demo



          Note:

          - vorher fragen, wer alles client braucht und noch accounts braucht, damit wir wissen,

          wieviel zeit wir uns für try git nehmen können

          - config

          - init

          - git add foo bar

          - git commit -m 'foo bar'

          - prima

        </section>

      </section>



      <section>

        <section id="prereq" class="titleslide slide level1" data-markdown>

          ### Block 1

          ## Checking Prerequisites



          - GitHub / GitLab account

          - local git client installation

          - bonus: your own project without VCS



          Note:

          - wenn git client selbst nicht aufsetzen kann, dann bitte halbe stunde früher

          - registration to the course

          - git client includes your own notebook

        </section>

      </section>





          <section class="slide level2" data-markdown>

            ## 



            - 



            Note:

            - 

          </section>

        </section>



        <section>

          <section class="titleslide slide level1" data-markdown>

            # VCS for me



            - 



            Note:

            - 

          </section>



          <section class="slide level2" data-markdown>

            ## 



            - 



            Note:

            - 

          </section>

        </section>



        <section>

          <section class="titleslide slide level1" data-markdown>

            # 



            - 



            Note:

            - 

          </section>



          <section class="slide level2" data-markdown>

            ## 



            - 



            Note:

            - 

          </section>

        </section>



        <section id="eof" data-background="img/trex.png"><h1>EOF</h1></section>

      </div>

    </div>



    <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,

        history: true,

        center: 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>

img/git-remote-contributor.dot

+7 −7
Original line number Original line Diff line number Diff line
@@ -6,7 +6,7 @@ digraph { 




        node [color = orchid]

        node [color = orchid]





        omaster[label = "master"]

        omain[label = "main"]

    }

    }





    subgraph clusterlocal {

    subgraph clusterlocal {
@@ -14,7 +14,7 @@ digraph { 




        node [color = orchid]

        node [color = orchid]





        master[label = "master"]

        main[label = "main"]

    }

    }





    subgraph clusterupstream {

    subgraph clusterupstream {
@@ -22,11 +22,11 @@ digraph { 




        node [color = limegreen]

        node [color = limegreen]





        umaster[label = "master"]

        umain[label = "main"]

    }

    }





    omaster -> master [label = "git pull"]

    omain -> main [label = "git pull"]

    master -> omaster [label = "git push", constraint = false]

    main -> omain [label = "git push", constraint = false]

    umaster -> master [label = "git pull upstream master", constraint = false]

    umain -> main [label = "git pull upstream main", constraint = false]

    omaster -> umaster [label = "pull request (GitHub)\nmerge request (GitLab)", constraint = false]

    omain -> umain [label = "pull request (GitHub)\nmerge request (GitLab)", constraint = false]

}
 
}

img/git-remote-maintainer.dot

+8 −8
Original line number Original line Diff line number Diff line
@@ -6,7 +6,7 @@ digraph { 




        node [color = orchid]

        node [color = orchid]





        omaster[label = "master"]

        omain[label = "main"]

    }

    }





    subgraph clusterlocal {

    subgraph clusterlocal {
@@ -14,7 +14,7 @@ digraph { 




        node [color = orchid]

        node [color = orchid]





        master[label = "master"]

        main[label = "main"]

    }

    }





    subgraph clusteralice {

    subgraph clusteralice {
@@ -22,7 +22,7 @@ digraph { 




        node [color = limegreen]

        node [color = limegreen]





        amaster[label = "master"]

        amain[label = "main"]

    }

    }





    subgraph clusterbob {

    subgraph clusterbob {
@@ -30,11 +30,11 @@ digraph { 




        node [color = lightskyblue]

        node [color = lightskyblue]





        bmaster[label = "master"]

        bmain[label = "main"]

    }

    }





    omaster -> master [label = "git pull"]

    omain -> main [label = "git pull"]

    master -> omaster [label = "git push", constraint = false]

    main -> omain [label = "git push", constraint = false]

    amaster -> master [label = "git pull alice", constraint = false]

    amain -> main [label = "git pull alice", constraint = false]

    bmaster -> master [label = "git pull bob", constraint = false]

    bmain -> main [label = "git pull bob", constraint = false]

}
 
}

img/git-remote-solo.dot

+5 −5
Original line number Original line Diff line number Diff line
@@ -9,7 +9,7 @@ digraph { 




        node [color = orchid]

        node [color = orchid]





        omaster[label = "master"]

        omain[label = "main"]

    }

    }





    subgraph clusterlocal {

    subgraph clusterlocal {
@@ -17,10 +17,10 @@ digraph { 




        node [color = orchid]

        node [color = orchid]





        master[label = "master"]

        main[label = "main"]

    }

    }





    omaster -> master [label = "git fetch", style = dotted, ltail = clusterorigin, lhead = clusterlocal]

    omain -> main [label = "git fetch", style = dotted, ltail = clusterorigin, lhead = clusterlocal]

    master -> omaster [label = "git push"]

    main -> omain [label = "git push"]

    omaster -> master [label = "git pull"]

    omain -> main [label = "git pull"]

}
 
}

img/motivation-structure.dot

0 → 100644
+10 −0
Original line number Original line Diff line number Diff line 
digraph {

    node [shape = "box", style = "filled, rounded"]



    master4[label = "Alice (today)\nfixes logic error", color = limegreen]

    master3[label = "Bob (yesterday)\nfixes typos", color = darkorchid1]

    master2[label = "Alice (three days ago)\nadds methods chapter", color = limegreen]

    master1[label = "...", color = grey]



    master4 -> master3 -> master2 -> master1

}

img/motivation-throwaway-playground.dot

+9 −9
Original line number Original line Diff line number Diff line 
digraph {

digraph {

    node [shape = "box", style = "filled, rounded"]

    node [shape = "box", style = "filled, rounded"]





    subgraph clustermaster {

    subgraph clustermain {

        label = "master"

        label = "main"





        node [color = limegreen]

        node [color = limegreen]





        master3[label = "ebe0262"]

        main3[label = "..."]

        master2[label = "03f4f8d"]

        main2[label = "..."]

        master1[label = "62a0ee9"]

        main1[label = "..."]





        master3 -> master2 -> master1

        main3 -> main2 -> main1

    }

    }





    subgraph clusterplayground {

    subgraph clusterplayground {
@@ -18,11 +18,11 @@ digraph { 




        node [color = orchid]

        node [color = orchid]





        playground2[label = "8b29f74"]

        playground2[label = "visualization"]

        playground1[label = "7f295dd"]

        playground1[label = "methods"]





        playground2 -> playground1

        playground2 -> playground1

    }

    }





    playground1 -> master2

    playground1 -> main2

}
 
}

img/rdm-use-case-data.dot

0 → 100644
+32 −0
Original line number Original line Diff line number Diff line 
digraph {

    compound = true

    node [shape = "box", style = "filled, rounded"]



    subgraph cluster_script {

        label = "scripts"



        node [color = lightskyblue]



        script_version_b[label = "nature-v2"]

    }



    subgraph cluster_data {

        label = "data repository (not git!)"



        node [color = limegreen]



        data_version_a[label = "doi:blah/blah"]

    }



    subgraph cluster_paper {

        label = "paper"



        node [color = limegreen]



        paper_version_c[label = "nature-final"]

    }



    paper_version_c -> data_version_a [label = "\n\n", lhead = cluster_data]



    data_version_a -> script_version_b [label = "\n\n", lhead = cluster_script]

}

img/rdm-use-case-merged.dot

0 → 100644
+63 −0
Original line number Original line Diff line number Diff line 
digraph {

    compound = true

    node [shape = "box", style = "filled, rounded"]



    subgraph cluster_script {

        label = "scripts"



        node [color = lightskyblue]



        script_version_b[label = "nature-v2"]

        script_version_a[label = "nature-v1"]

    }



    subgraph cluster_data {

        label = "data repository (not git!)"



        node [color = limegreen]



        data_version_a[label = "doi:blah/blah"]

    }



    subgraph cluster_paper {

        label = "paper"



        node [color = limegreen]



        paper_version_a[label = "nature-review-1"]

        paper_version_b[label = "nature-review-2"]

        paper_version_c[label = "nature-final"]

    }



    subgraph cluster_software_a {

        label = "software A"



        node [color = orchid]



        software_a_version_a[label = "v2.1.6"]

    }



    subgraph cluster_software_b {

        label = "software B"



        node [color = orchid]



        software_b_version_b[label = "v0.3.4"]

        software_b_version_a[label = "v0.2.0"]

    }



    script_version_a -> software_a_version_a [label = "\n\n"]

    script_version_b -> software_a_version_a [label = "\n\n"]



    script_version_a -> software_b_version_a [label = "\n\n"]

    script_version_b -> software_b_version_b [label = "\n\n"]



    paper_version_a -> script_version_a [label = "\n\n"]

    paper_version_b -> script_version_b [label = "\n\n"]

    paper_version_c -> script_version_b [label = "\n\n"]



    paper_version_c -> data_version_a [label = "\n\n"]



    data_version_a -> script_version_b [label = "\n\n"]



}

img/rdm-use-cases-a.dot

0 → 100644
+42 −0
Original line number Original line Diff line number Diff line 
digraph {

    compound = true

    node [shape = "box", style = "filled, rounded"]



    subgraph cluster_software_a {

        label = "software A"



        node [color = orchid]



        software_a_version_a[label = "v2.1.6"]

    }



    subgraph cluster_software_b {

        label = "software B"



        node [color = orchid]



        software_b_version_a[label = "v0.2.0"]

    }



    subgraph cluster_script {

        label = "scripts"



        node [color = lightskyblue]



        script_version_a[label = "nature-v1"]

    }



    subgraph cluster_paper {

        label = "paper"



        node [color = limegreen]



        paper_version_a[label = "nature-review-1"]

    }



    script_version_a -> software_a_version_a [label = "\n\n"]



    script_version_a -> software_b_version_a [label = "\n\n"]



    paper_version_a -> script_version_a [label = "\n\n"]

}

img/rdm-use-cases-b.dot

0 → 100644
+48 −0
Original line number Original line Diff line number Diff line 
digraph {

    compound = true

    node [shape = "box", style = "filled, rounded"]



    subgraph cluster_software_a {

        label = "software A"



        node [color = orchid]



        software_a_version_a[label = "v2.1.6"]

    }



    subgraph cluster_software_b {

        label = "software B"



        node [color = orchid]



        software_b_version_b[label = "v0.3.4"]

        software_b_version_a[label = "v0.2.0"]

    }



    subgraph cluster_script {

        label = "scripts"



        node [color = lightskyblue]



        script_version_b[label = "nature-v2"]

        script_version_a[label = "nature-v1"]

    }



    subgraph cluster_paper {

        label = "paper"



        node [color = limegreen]



        paper_version_a[label = "nature-review-1"]

        paper_version_b[label = "nature-review-2"]

    }



    script_version_a -> software_a_version_a [label = "\n\n"]

    script_version_b -> software_a_version_a [label = "\n\n"]



    script_version_a -> software_b_version_a [label = "\n\n"]

    script_version_b -> software_b_version_b [label = "\n\n"]



    paper_version_a -> script_version_a [label = "\n\n"]

    paper_version_b -> script_version_b [label = "\n\n"]

}

img/rdm-use-cases.dot

0 → 100644
+50 −0
Original line number Original line Diff line number Diff line 
digraph {

    compound = true

    node [shape = "box", style = "filled, rounded"]



    subgraph cluster_software_a {

        label = "software A"



        node [color = orchid]



        software_a_version_a[label = "v2.1.6"]

    }



    subgraph cluster_software_b {

        label = "software B"



        node [color = orchid]



        software_b_version_b[label = "v0.3.4"]

        software_b_version_a[label = "v0.2.0"]

    }



    subgraph cluster_script {

        label = "scripts"



        node [color = lightskyblue]



        script_version_b[label = "nature-v2"]

        script_version_a[label = "nature-v1"]

    }



    subgraph cluster_paper {

        label = "paper"



        node [color = limegreen]



        paper_version_a[label = "nature-review-1"]

        paper_version_b[label = "nature-review-2"]

        paper_version_c[label = "nature-final"]

    }



    script_version_a -> software_a_version_a [label = "\n\n"]

    script_version_b -> software_a_version_a [label = "\n\n"]



    script_version_a -> software_b_version_a [label = "\n\n"]

    script_version_b -> software_b_version_b [label = "\n\n"]



    paper_version_a -> script_version_a [label = "\n\n"]

    paper_version_b -> script_version_b [label = "\n\n"]

    paper_version_c -> script_version_b [label = "\n\n"]

}

img/staging-area-diff.dot

0 → 100644
+10 −0
Original line number Original line Diff line number Diff line 
digraph {

    node [shape = "box", style = "filled,rounded"]



    workdir[label = "working directory\n(changes not staged for commit)", color = lightskyblue]

    stage[label = "staging area\n(changes to be committed)", color = orchid]

    repo[label = "repository\n(tracked content)", color = limegreen]



    workdir -> stage [label = "git diff"]

    stage -> repo [label = "git diff --staged"]

}

img/staging-area.dot

+3 −3
Original line number Original line Diff line number Diff line
@@ -10,10 +10,10 @@ digraph { 
    # untracked -> stage [label = "git add"]

    # untracked -> stage [label = "git add"]

    # stage -> untracked [label = "git unstage"]

    # stage -> untracked [label = "git unstage"]





    workdir -> stage [label = "git stage file"]

    workdir:sw -> stage:w [label = "git stage file"]

    stage -> workdir [label = "git unstage file"]

    stage:e -> workdir:se [xlabel = "git unstage file"]





    # workdir -> discard [label = "git checkout"]

    # workdir -> discard [label = "git restore"]

    # untracked -> discard [label = "rm"]

    # untracked -> discard [label = "rm"]





    stage -> repo [label = "git commit"]

    stage -> repo [label = "git commit"]

notes.md

deleted100644 → 0
+0 −92
Original line number Original line Diff line number Diff line 
Basics

======



VCS für mich

------------



### config



### init



### add



git add foo bar



### commit



git commit -m 'foo bar'



prima -



was hat sich nu verändert?

--------------------------



### log



--stat



-p



### diff



- was ändern

- git diff

- git commit -am



### repo / stage / working



- grafik raussuchen

- wofür nutzen



### add / reset / checkout



diff und diff --staged und diff HEAD



vcs mit backup

--------------



- github neues projekt --> projekteinbindung: clone / remote add origin foo

- push

- pull







## merge



mergetool linux = meld

mac = ???

windows = ???



Workflows

=========



branching workflows

-------------------



was sind branches und wofür brauch ich sie? diese frage sollte eindeutig in diesem kapitel erklärt

werden.



### nvie successful git branching model



### multi master



paper with many journals



same paper text  -  different theme file for page layout, graph layout, etc.



## tips for papers



git diff -w --ignore-blank-lines --word-diff



Your Projects

=============









##### STuff



- explain all collaboration workflows via github





-

overview.md

deleted100644 → 0
+0 −23
Original line number Original line Diff line number Diff line 
Blöcke

======



each block is about 3 hours e.g. 9 - 12 including breaks



0.  Intro

    - Why git?

    - git installation hands on

    - show try git like tutorial on beamer (closed laptops)

    - hands on - created project

    - wrap up hands on



1.  Git Commands

    - working dir - index/stage - repo



2.  GitLab / GitHub

    - project maintanance

    - issues and PRs

    - "easier collaboration"



3.  VCS Workflows

    - how to collaborate in an organized manner

pandoc-cheat-sheet @ 2346a002

Original line number Original line Diff line number Diff line 
Subproject commit 2346a002289757ee612bfd4b56b57db53e0c751b

pandoc-papers.md

0 → 100644
+218 −0
Original line number Original line Diff line number Diff line 
---

title: pandoc papers

subtitle: a future proof way to write

author:

- Christian Krause

...



intro

=====



## motivation #1



![](img/motivation-draft-mess-half-size.png)



## motivation #2



- **focus** on content/writing

- **communication**

  - avoid emails with attachments, right?

  - early and frequent reviews

- get rid of MS Word, Google Docs, Dropbox, etc.



## motivation #3



- use **version control** with all its benefits

- **automated**

  - spell checking

  - high quality typesetting

  - publishing

- **future proof** way of doing things, meaning

  - tools are open source

  - tools are replaceable or optional

  - all content is plain text



## agenda



- short presentation including demo

- learn tools and workflows

- establish community





tools

=====



## pandoc -- Swiss Army Knife of Text Conversion



### source: markup



- usually **Markdown**

- less powerful than \LaTeX, but inline \LaTeX\ can be used



### target**s**



- high quality PDF via \LaTeX

- others: HTML web page, EPUB, Office documents



### templates



- different journals

- iDiv branding



## Markdown



### source



```

- **easy to learn**, read and write

- ~~no~~ fewer distractions to *procrastinate*

- inline \LaTeX\ if needed \rightarrow\ $a^2 + b^2 = c^2$

```



### rendered



- **easy to learn**, read and write

- ~~no~~ fewer distractions to *procrastinate*

- inline \LaTeX\ if needed \rightarrow\ $a^2 + b^2 = c^2$



## git & GitLab



### git



- version control

- free backup



### GitLab: [https://git.idiv.de](https://git.idiv.de)



- self-hosted, full access control

- communication: discussion and reviews

- continuous integration i.e. spell checking

- continuous deployment to e.g. cloud storage



## visualization



### Graphviz/dot



- graph visualization language

- define flowcharts with code

- **dot** handles rendering to **SVG**



### plotting



- any *programming language* can be used

- add results as **CSV** to repository

- plot data to **SVG** e.g. using **R** with **ggplot2** and **svglite**



## build tool



### make



- glues everything together

- automates build

  - render images from **dot** and **CSV** sources

  - build PDF

  - run spell check





workflow

========



## workflow #1



### [set up new project in GitLab](https://git.idiv.de/projects/new)



- use project template

- template is managed by our community

- contains Makefile, README, CI/CD, ~~themes~~, visualization examples, etc.



### writing



- start writing the main document in Markdown

- use text editor you're comfortable with



## workflow #2



### communication



- invite contributors / collaborators to GitLab project

- use GitLab project as main communication platform

- discuss and review in

  - commit comments

  - issues

  - merge requests



## workflow #3



### continuous deployment



- some parts are done automatically with the project template

- deploy PDF to cloud storage:

  [https://portal.idiv.de/nextcloud/](https://portal.idiv.de/nextcloud/)

- (uses **DRAFT** watermark ~~if commit not tagged~~)



## demo



(demo here only if all tools are already installed)





your turn

=========



## discussion



- Which tools do you currently use?

  - Anyone know **pandoc-scholar**?

  - Anyone know **authorea**?

- What are your workflows?

- How do you communicate, collaborate and review?

- What annoys you the most? (i.e. how can we improve)



## let's get started



### create new project



- https://git.idiv.de/projects/new

- **create from template** \rightarrow\ **instance** \rightarrow\ **pandoc**

- install tools from `README.md`

- set up Nextcloud share and CD



### editor: Atom



- **atom-latex** for bib syntax highlighting

- **graphviz-preview-plus** for dot syntax highlighting and preview

- **hard-wrap** for wrapping paragraphs

- **language-pfm** for pandoc flavored Markdown

- **language-r** for R



## issues



### prose diff tool



- hard wrap vs soft wrap

- these issues might help:

  [gitlab-ce#25650](https://gitlab.com/gitlab-org/gitlab-ce/issues/25650),

  [gitlab-ce#26804](https://gitlab.com/gitlab-org/gitlab-ce/issues/26804)

- [https://github.blog/2014-02-14-rendered-prose-diffs/](https://github.blog/2014-02-14-rendered-prose-diffs/)



### spell checking



- integrate editor spell checking with **mdspell**

- per project editor integration

- needs additional ignores, e.g. links, \LaTeX\ and citations





community

=========



## contributing



### [https://git.idiv.de/publishing](https://git.idiv.de/publishing)



- contribute to **project template** about build / workflow related issues

  - e.g. if you need more packages for plotting

- contribute to **bibliography** about new references

  - we may even import/sync an existing publication database

- contribute to **pandoc templates**

  - had no need for them yet

  - we might add some iDiv corporate identity (talk with PR)

  - **review-able** template with link to join discussion at every paragraph

rdm.html

0 → 100644
+498 −0
Original line number Original line Diff line number Diff line 
<!DOCTYPE html>

<html>

  <head>

    <title>git@rdm</title>

    <link rel="stylesheet" href="reveal.js/dist/reveal.css">

    <link rel="stylesheet" href="reveal.js/dist/theme/black.css">

    <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 and rdm

            ## (... and reproducibility)



            notes:

            - `make -B` to create images, then reload

          </section>



          <section id="intro-objectives" data-markdown>

            ## objectives



            - show how git relates to RDM

            - ... and reproducibility

          </section>



          <section id="intro-agenda" data-markdown>

            ## agenda



            1.  motivation

            1.  ~~teach ***how*** to use git/GitHub/GitLab~~

            1.  use cases

            1.  anti-patterns

            1.  platforms

            1.  Q & A



            notes:

            - feel free to interrupt with immediate questions

            - more involved detailed discussion as part of Q & A

          </section>



          <section id="intro-version-control" data-markdown>

            ## about version control



            > records changes



            what who when (why)



            notes:

            - the **why** (aka context) is optional

              - you have to do this

              - you have to care about it

          </section>



          <section id="intro-about-git" data-markdown>

            ## about git



            ### best tool for the job



            - simple by design

            - powerful if needed

            - documentation / community

            - industry standard



            notes:

            - git name: "the stupid content tracker"

            - doc: finding answers with web searches

          </section>



          <section id="intro-about-me" data-markdown>

            ## about me



            - scientific computing support @ iDiv since 2014

            - satisfied git user since 2010



            > There will never be a better version control system than git.

            >

            > -- Christian Krause, 2017

          </section>



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

            ## about you



            ![people](img/people.jpg)



            notes:

            - who has never used any VCS before?

            - who actively maintains a VCS repository?

          </section>

        </section>



        <!---------------------------------------------------------------------

        <!-- motivation

        <!-------------------------------------------------------------------->



        <section>

          <section id="motivation" data-markdown>

            # motivation



            > Why should I use version control?



            notes:

            - motivation chapter is about the concept of version control

            - git is just a tool to do it

          </section>



          <section id="motivation-avoid-mess" data-markdown>

            ## motivation #1

            ### avoid mess



            ![blah](img/motivation-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/motivation-structure.svg)



            notes:

            - structure: who, when

            - why is hidden (only shows message header, not body)

            - ability to inspect old versions and their diff

            - ability to revert/undo a change

          </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 without pain

          </section>



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

            ## motivation #c

            ### collaboration made easy



            <!-- do not fix this typo, it is here on purpose to show collab -->

            > This text cntains a typo.



            notes:

            - demo GitLab (change **target branch** to create merge request)

            - this is how you can do reviews of drafts

              - discuss this slide/chapter/section link

          </section>



          <section id="motivation-collaboration-2" data-markdown>

            ## motivation #c



            ![typo-pr](https://pbs.twimg.com/media/EDsklbLUEAMdusJ.png)



            notes:

            - might not seem like much

            - but you are still making the world a better place

            - and it is not too much effort

          </section>



          <section id="motivation-automation" data-markdown>

            ## motivation #a

            ### automation



            - ***quality***

              - **code analysis**

              - **spell check**

              - **software testing**

              - enforce **style guide**

            - ***deployment*** (app store, web server)



            notes:

            - basically, everything you can script

            - refresh presentation before next slide

          </section>



          <section class="star-wars" id="motivation-wars">

            <div class="crawl">

              <div class="title">

                <h1>motivation #wars</h1>

              </div>



              <div data-markdown>

                1.  view the ***history*** of changes



                1.  know ***why*** someone changed it



                1.  ***revert*** a bad change



                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.  ***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>



        <!---------------------------------------------------------------------

        <!-- use cases

        <!-------------------------------------------------------------------->



        <section>

          <section id="use-cases" data-markdown>

            # use cases

            ##### for

            ### version control system (vcs)

            ##### aka

            ### source code management (scm)

          </section>



          <section id="use-case-software" data-markdown>

            ## software



            - generic (as in parameterized)

            - (ideally) tested



            notes:

            - e.g. R package

          </section>



          <section id="use-case-scripting" data-markdown>

            ## scripting

            ##### aka

            ### how to run `$software`



            - ... in `$environment`

            - digital lab notes

            - **reproducibility** !!1!

            - execution scalability



            notes:

            - separate software from scripting

            - `$enviroment`: multiple scripts/configurations for different

              environments:

              - EasyBuild, conda, singularity

              - RStudio server, HPC cluster

            - execution scalability: running software or script without having

              to change it

            - keep failed attempts in branches

              - e.g. highly parameterized software, make a record of bad

                parameter sets

          </section>



          <section id="use-case-publishing" data-markdown>

            # publishing

            ### (markdown (with some tex))



            - paper / thesis / book

            - presentation

            - documentation

            - blog



            notes:

            - who is using markdown?

            - who is using tex?

            - who is using word? why?

            - markdown with tex

              - git.idiv.de/help

              - search for markdown

              - search for math

              - show example

          </section>



          <section id="use-case-integrated-1" data-markdown>

            ## integration



            ![run `make` to generate the image](img/rdm-use-cases-a.svg)



            notes:

            - software A: tried and tested, reference to compare to

            - software B: your experimental better version

          </section>



          <section id="use-case-integrated-2" data-markdown>

            ## integration



            ![run `make` to generate the image](img/rdm-use-cases-b.svg)

          </section>



          <section id="use-case-integrated-3" data-markdown>

            ## integration



            ![run `make` to generate the image](img/rdm-use-cases.svg)

          </section>



          <section id="use-case-integrated-data" data-markdown>

            ## integration



            ![run `make` to generate the image](img/rdm-use-case-data.svg)

          </section>

        </section>



        <!---------------------------------------------------------------------

        <!-- anti patterns

        <!-------------------------------------------------------------------->



        <section>

          <section id="anti-patterns" data-markdown>

            # anti-patterns



            ![unlimited power](img/unlimited-power.jpg)



            notes:

            - does anyone know what an anti-pattern is?

          </section>



          <section id="anti-patterns-def" data-markdown>

            # anti-patterns



            > An anti-pattern is a common response to a recurring problem that

            is usually ineffective and risks being highly counterproductive.



            notes:

            - most anti-patterns about how to use git

            - focus here is on these relating to RDM and reproducibility

          </section>



          <section id="anti-pattern-binary" data-markdown>

            # binary files

            ### (aka non-text)



            - no diff with binary

            - use textual representation

            - convert with automation



            notes:

            - can someone give me an example of text file?

              - markdown

              - source code, scripts (R, shell)

              - XSV

            - can someone give me an example of binary file?

              - compiled programs

              - MS word excel

              - PDF PS

            - don't just put everything in the repo, use *ignore

          </section>



          <section id="anti-pattern-big-data" data-markdown>

            # data in git

            ## (scientific/big data)



            - version control for data is **DIFF**erent !!1!

            - git is VCS for text, not for data



            notes:

            - do you release data with every script change? no, too expensive

            - you don't ever put data files in a git repository

            - not even with LFS

            - big ball of mud, no metadata

          </section>

        </section>



        <!---------------------------------------------------------------------

        <!-- platforms

        <!-------------------------------------------------------------------->



        <section>

          <section id="platforms-list" data-markdown>

            # platforms



            - GitHub

              - https://github.com/idiv-biodiversity (cloud)

            - GitLab

              - https://gitlab.com (cloud)

              - https://git.idiv.de (self-hosted @ iDiv)

          </section>



          <section id="platforms-purpose" data-markdown>

            # platforms



            - enable collaboration

              - bug tracker / feature requests

              - documentation / wiki

            - project management tools

              - issue boards, milestones, gantt

            - trigger automation

            - publish/download releases

          </section>

        </section>



        <!---------------------------------------------------------------------

        <!-- q & a

        <!-------------------------------------------------------------------->



        <section>

          <section id="q-n-a" data-markdown>

            # Q & A



            notes:

            - walk through examples of software/script/publishing

            - walk through one of your use cases

              - demo consulting

          </section>



          <section id="consulting" data-markdown>

            # consulting



            [christian.krause@idiv.de](mailto:christian.krause@idiv.de)

          </section>

        </section>



        <!---------------------------------------------------------------------

        <!-- eof

        <!-------------------------------------------------------------------->



        <section id="eof" data-background="img/trex.png" data-markdown>

          ### thanks for listening

          # EOF

        </section>



        <!---------------------------------------------------------------------

        <!-- backup

        <!-------------------------------------------------------------------->



        <section>

          <section id="backup" data-markdown>

            # backup slides

          </section>



          <section id="empty" data-markdown>

          </section>

        </section>

      </div>

    </div>



    <!-------------------------------------------------------------------------

    <!-- css/js

    <!------------------------------------------------------------------------>



    <!-- 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/main/rdm.html"

            target="_blank">

          edit

        </a>

      </div>

    </div>



    <!-- reveal.stuff -->



    <script src="reveal.js/dist/reveal.js"></script>

    <script src="reveal.js/plugin/highlight/highlight.js"></script>

    <script src="reveal.js/plugin/markdown/markdown.js"></script>

    <script src="reveal.js/plugin/notes/notes.js"></script>



    <script>

      Reveal.initialize({

          hash: true,

          plugins: [RevealHighlight, RevealMarkdown, RevealNotes]

      });

    </script>

  </body>

</html>

rdm.md

0 → 100644
+131 −0
Original line number Original line Diff line number Diff line 
git for RDM and reproducibility

===============================



checklist

---------



- **software** (a generic tool to do *something*)

  - [ ] use separate git repo for software

  - [ ] tag versions for reproducibility

  - [ ] keep software as generic as possible

- **scripts** (*how* to use *software*)

  - [ ] use separate git repo for scripts

  - [ ] tag versions for reproducibility

  - [ ] software is configured here

  - [ ] reference used software tag

- **data management**

  - [ ] publish dataset(s) to scientific data archive system

  - [ ] always attach proper metadata

  - [ ] get DOI for each version of the dataset(s) for reproducibility

  - [ ] reference used scripts tag

- **publishing**

  - [ ] use separate git repo for paper/thesis/...

  - [ ] tag versions for draft/review/final

  - [ ] convert text/source to (binary) products

  - [ ] reference used scripts tag

  - [ ] reference used data DOI

- **platforms** (GitLab, GitHub)

  - [ ] use platforms (GitLab, GitHub) for collaboration

  - [ ] review commits / merge requests

  - [ ] utilize project management tools

  - [ ] utilize automation for testing and publishing





intro

-----



- version control system (VCS) records changes (what, who, when, why)

- use platforms (GitLab, GitHub) for collaboration





git use cases

-------------



### software



- keep software as generic as possible

- turn configuration/parameters into arguments, e.g. `myapp --seed=42`

- this avoids having to rewrite software for parameter changes

- use software testing to verify software does what it's supposed to do

- tag versions to enable **reproducibility**



### scripting



- separate scripting from software

  - software: generic

  - scripting: software called with specific configuration/arguments

- scripting means **how** to run the software

  - i.e. here is where the parameters/arguments go

  - think of it as digital lab notes

  - this enables **reproducibility**

- specialized script variants for different environments, e.g.

  - laptop

  - RStudio / terminal server

  - HPC cluster

- think about *execution scalability*, i.e. not having to change software and

  scripting when you want to change parameters

- keep failed attempts in branches to keep history of what you tried and why it

  didn't work in commit message



### publishing



- for paper, thesis, book, presentation, documentation, blog posts

  - use *programming languages* code/scripts for plots, flowcharts, etc.

  - write text/paragraphs in markup language (e.g. markdown)

- use automation workflows to

  - generate plot/flowchart code to image files

  - convert text with pandoc to PDF/PS/HTML/ebup

- use platforms for review process



## integration of use cases for reproducibility



![](img/rdm-use-case-merged.svg)





anti patterns

-------------



> An anti-pattern is a common response to a recurring problem that is usually

> ineffective and risks being highly counterproductive.



- most git anti-patterns are about *how* to use git

- focus here is on these relating to RDM and reproducibility



### binary files



- git as VCS only good for text files

  - markdown

  - source code, scripts

  - (small) CSV

- binary files can't be diff'ed, e.g.

  - compiled programs

  - MS word, excel

  - PDF, PS

  - JPEG, PNG

- use textual representation, e.g.

  - graphviz dot for flowcharts

  - R ggplot and CSV for plots

- use automation to convert textual representation to e.g. images

- use gitignore to never add binary products to the repo



### scientific data in git repos



- data is often binary

- git repo should be small, data blows it up, even if text

- data has different release cycles than code

- even git lfs (large file storage) is bad because still big ball of mud

  - scientific datasets need metadata!

- use proper archive system for data





platforms

---------



- enable collaboration

  - bug tracker / feature requests

  - documentation / wiki

- project management tools

  - issue boards, milestones, gantt

- trigger automation

- publish/download releases

- go to https://git.idiv.de log in and create new projects!

rdm.yml

0 → 100644
+37 −0
Original line number Original line Diff line number Diff line 
---

# these are not shown in the document, they are just for metadata

title: git RDM reproducibility check list cheat sheet

author: Christian Krause

lang: en

keywords:

  - git

  - RDM

  - resource data management

  - reproducibility



# highlighting increases readability

linkcolor: blue



# these LaTeX variables fit as much content on as few pages as possible

documentclass: scrartcl

pagestyle: empty

papersize: a4paper

geometry:

  - a4paper

  - left=1cm

  - right=1cm

  - top=1cm

  - bottom=1cm

# you can also add "landscape" to geometry if you want more than 2 columns



# fiddle with these to increase readability

columns: 2

fontsize: 9pt



# this essentially disables justification, which can increase readability

ragged: yes



# color for header background

sectionbg: BurntOrange

subsectionbg: Apricot

...