377 lines
8.3 KiB
Plaintext
377 lines
8.3 KiB
Plaintext
|
= Document Version Control with GIT
|
||
|
|
:customcss: custom_css.css
|
||
|
|
:imagesdir: img
|
||
|
|
:title-slide-background-image: intro.jpg
|
||
|
|
:background-image: normal.jpg
|
||
|
|
:revealjs_theme: white
|
||
|
|
:revealjs_margin: 0.1
|
||
|
|
:revealjs_width: 1920
|
||
|
|
:revealjs_height: 1200
|
||
|
|
|
||
|
|
== Before we start...
|
||
|
|
|
||
|
|
image::nocloud.jpg[scaledwith=60%]
|
||
|
|
|
||
|
|
== What is version control?
|
||
|
|
|
||
|
|
[%step]
|
||
|
|
* Version control is a system that records changes to a file or set of files over time so that you can recall specific versions later.
|
||
|
|
* Has existed for almost as long as writing has existed (ex. document version)
|
||
|
|
* Today, the most capable (as well as complex) revision control systems are those used in software development.
|
||
|
|
|
||
|
|
=== Why?
|
||
|
|
|
||
|
|
[%step]
|
||
|
|
* Revert files back to a previous state
|
||
|
|
* "Freeze" important versions of a document
|
||
|
|
* Compare changes over time
|
||
|
|
* Track progress of a project
|
||
|
|
* See who modified something, and when
|
||
|
|
|
||
|
|
=== Modern version control systems
|
||
|
|
|
||
|
|
[%step]
|
||
|
|
* Remote backup of files
|
||
|
|
* Powerful tool for collaboration
|
||
|
|
|
||
|
|
== GIT
|
||
|
|
|
||
|
|
[%step]
|
||
|
|
* Developed by Linus Torvalds in 2005
|
||
|
|
* The linux Kernel:
|
||
|
|
** ~63000 files
|
||
|
|
** Roughly 15,600 developers from more than 1,400 companies
|
||
|
|
|
||
|
|
=== Characteristics
|
||
|
|
|
||
|
|
[%step]
|
||
|
|
* Free and open source
|
||
|
|
* Distributed
|
||
|
|
* Powerful and flexible
|
||
|
|
* Learning curve can be steep
|
||
|
|
|
||
|
|
=== !
|
||
|
|
|
||
|
|
image:xkcd_git.png[]
|
||
|
|
|
||
|
|
=== How does it work?
|
||
|
|
|
||
|
|
image::architecture.png[]
|
||
|
|
|
||
|
|
=== Installation
|
||
|
|
|
||
|
|
https://git-scm.com/download/win
|
||
|
|
|
||
|
|
Package managers are heavily recommended!
|
||
|
|
|
||
|
|
|
||
|
|
=== Creating a remote repository
|
||
|
|
|
||
|
|
[%step]
|
||
|
|
* register at the remote git server
|
||
|
|
** https://git.webhosting.rug.nl/
|
||
|
|
* create repository
|
||
|
|
* add participants __ssh public keys__
|
||
|
|
* clone the repository in your machine
|
||
|
|
|
||
|
|
=== README and .gitignore
|
||
|
|
|
||
|
|
Every repository should have these 2 files:
|
||
|
|
|
||
|
|
* **README**: project description and useful information
|
||
|
|
* **.gitignore**: special file indicating GIT which files are **not** to be tracked
|
||
|
|
|
||
|
|
=== workflow
|
||
|
|
|
||
|
|
image::git_workflow.jpg[]
|
||
|
|
|
||
|
|
=== copying remote repository: clone
|
||
|
|
|
||
|
|
* **git clone __repository__**
|
||
|
|
* Clones the remote repository into the local one
|
||
|
|
|
||
|
|
=== staging changes (local)
|
||
|
|
|
||
|
|
|
||
|
|
[%step]
|
||
|
|
* **git add __files__**
|
||
|
|
* Adds the changes into the local staging area
|
||
|
|
|
||
|
|
=== Saving changes: commit (local)
|
||
|
|
|
||
|
|
[%step]
|
||
|
|
* **git commit "message"**
|
||
|
|
* Saves the changes in the staging area into the repository
|
||
|
|
* Creates a "snapshot" of the current state of one or more files
|
||
|
|
* A message describing the changes must be provided
|
||
|
|
|
||
|
|
=== history and revert (local)
|
||
|
|
|
||
|
|
[%step]
|
||
|
|
* **git log __files__**
|
||
|
|
* returns a history of the file modifications
|
||
|
|
* **git revert __commit__**
|
||
|
|
* removes one or more commits from the local files, changes must be committed after
|
||
|
|
|
||
|
|
=== upload to remote repository: push
|
||
|
|
|
||
|
|
[%step]
|
||
|
|
* **git push**
|
||
|
|
* Uploads the state of the local repository to the remote one
|
||
|
|
|
||
|
|
=== Download from remote repository: pull
|
||
|
|
|
||
|
|
[%step]
|
||
|
|
* **git pull**
|
||
|
|
* Fetch and merges the documents in the remote repository into the local one
|
||
|
|
* Merging files can generate conflicts, git will ask us to fix them and commit the changes
|
||
|
|
|
||
|
|
=== Branching
|
||
|
|
|
||
|
|
image::version-control-flow.png[]
|
||
|
|
|
||
|
|
=== other (advanced) stuff
|
||
|
|
|
||
|
|
* tags
|
||
|
|
* partial reverts
|
||
|
|
* change history
|
||
|
|
* ...
|
||
|
|
|
||
|
|
== Docs as code
|
||
|
|
|
||
|
|
[%step]
|
||
|
|
* Software is a small part of the documents a project must handle
|
||
|
|
* Still, version control and remote collaboration are needed for all the documents
|
||
|
|
* In the last years there is a big push of treating documents the same way as programming files
|
||
|
|
** https://www.writethedocs.org/guide/docs-as-code/
|
||
|
|
|
||
|
|
=== Advantages
|
||
|
|
|
||
|
|
[%step]
|
||
|
|
* Working in plain text files (rather than binary file formats like Word)
|
||
|
|
* Collaborating using version control such as git and GitHub
|
||
|
|
* Storing docs in the same repositories as the programming code itself
|
||
|
|
* Versioning docs through git tags/releases (rather than duplicating all the files to archive each release)
|
||
|
|
* Generate other formats or websites without modifying the document
|
||
|
|
|
||
|
|
=== Just a little problem...
|
||
|
|
|
||
|
|
[%step]
|
||
|
|
* The most common document formats: word, pdf... are binary files
|
||
|
|
* git (text based) doesn't work with them
|
||
|
|
|
||
|
|
=== Solutions?
|
||
|
|
|
||
|
|
[%step]
|
||
|
|
* Markup languages:
|
||
|
|
* Markup languages are ways of annotating an electronic document.
|
||
|
|
* Usually markup will either specify how something should be displayed or what something means.
|
||
|
|
** html, xml, latex...
|
||
|
|
|
||
|
|
=== Markup languages
|
||
|
|
|
||
|
|
[%step]
|
||
|
|
* Documents are written in plain text, then a program convert them into the final document
|
||
|
|
* The same document can be used to generate files in other formats: latex, word, pdf or even slides
|
||
|
|
* Formating is done by the computer, output is always consistent
|
||
|
|
* Fast and light
|
||
|
|
* Can be used in version control systems
|
||
|
|
|
||
|
|
=== Markup languages: Advanced features
|
||
|
|
|
||
|
|
[%step]
|
||
|
|
* Automatic generation of documents
|
||
|
|
* Inline comments (not rendered in the final document)
|
||
|
|
* Split one the document into several. Ex: main document, chapters and bibliography
|
||
|
|
* Code executed and plots rendered __in__ the document
|
||
|
|
|
||
|
|
|
||
|
|
=== Latex
|
||
|
|
|
||
|
|
[%step]
|
||
|
|
* Extensively used for technical papers
|
||
|
|
* Beautiful generated documents
|
||
|
|
* Very powerful...
|
||
|
|
* ...and very heavy
|
||
|
|
* Setup and document customization are complex
|
||
|
|
|
||
|
|
=== Latex: example
|
||
|
|
|
||
|
|
----
|
||
|
|
|
||
|
|
|
||
|
|
\documentclass{article}
|
||
|
|
\usepackage{graphicx}
|
||
|
|
|
||
|
|
\begin{document}
|
||
|
|
|
||
|
|
\title{Introduction to \LaTeX{}}
|
||
|
|
\author{Author's Name}
|
||
|
|
|
||
|
|
\maketitle
|
||
|
|
|
||
|
|
\begin{abstract}
|
||
|
|
The abstract text goes here.
|
||
|
|
\end{abstract}
|
||
|
|
|
||
|
|
\section{Introduction}
|
||
|
|
Here is the text of your introduction.
|
||
|
|
|
||
|
|
\begin{equation}
|
||
|
|
\label{simple_equation}
|
||
|
|
\alpha = \sqrt{ \beta }
|
||
|
|
\end{equation}
|
||
|
|
|
||
|
|
\subsection{Subsection Heading Here}
|
||
|
|
Write your subsection text here.
|
||
|
|
|
||
|
|
\begin{figure}
|
||
|
|
\centering
|
||
|
|
\includegraphics[width=3.0in]{myfigure}
|
||
|
|
\caption{Simulation Results}
|
||
|
|
\label{simulationfigure}
|
||
|
|
\end{figure}
|
||
|
|
|
||
|
|
\section{Conclusion}
|
||
|
|
Write your conclusion here.
|
||
|
|
|
||
|
|
\end{document}
|
||
|
|
|
||
|
|
----
|
||
|
|
|
||
|
|
|
||
|
|
=== Latex: example II
|
||
|
|
|
||
|
|
----
|
||
|
|
\documentclass[12pt]{article}
|
||
|
|
\usepackage{lingmacros}
|
||
|
|
\usepackage{tree-dvips}
|
||
|
|
\begin{document}
|
||
|
|
|
||
|
|
\section*{Notes for My Paper}
|
||
|
|
|
||
|
|
Don't forget to include examples of topicalization.
|
||
|
|
They look like this:
|
||
|
|
|
||
|
|
{\small
|
||
|
|
\enumsentence{Topicalization from sentential subject:\\
|
||
|
|
\shortex{7}{a John$_i$ [a & kltukl & [el &
|
||
|
|
{\bf l-}oltoir & er & ngii$_i$ & a Mary]]}
|
||
|
|
{ & {\bf R-}clear & {\sc comp} &
|
||
|
|
{\bf IR}.{\sc 3s}-love & P & him & }
|
||
|
|
{John, (it's) clear that Mary loves (him).}}
|
||
|
|
}
|
||
|
|
|
||
|
|
\subsection*{How to handle topicalization}
|
||
|
|
|
||
|
|
I'll just assume a tree structure like (\ex{1}).
|
||
|
|
|
||
|
|
{\small
|
||
|
|
\enumsentence{Structure of A$'$ Projections:\\ [2ex]
|
||
|
|
\begin{tabular}[t]{cccc}
|
||
|
|
& \node{i}{CP}\\ [2ex]
|
||
|
|
\node{ii}{Spec} & &\node{iii}{C$'$}\\ [2ex]
|
||
|
|
&\node{iv}{C} & & \node{v}{SAgrP}
|
||
|
|
\end{tabular}
|
||
|
|
\nodeconnect{i}{ii}
|
||
|
|
\nodeconnect{i}{iii}
|
||
|
|
\nodeconnect{iii}{iv}
|
||
|
|
\nodeconnect{iii}{v}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
|
||
|
|
\subsection*{Mood}
|
||
|
|
|
||
|
|
Mood changes when there is a topic, as well as when
|
||
|
|
there is WH-movement. \emph{Irrealis} is the mood when
|
||
|
|
there is a non-subject topic or WH-phrase in Comp.
|
||
|
|
\emph{Realis} is the mood when there is a subject topic
|
||
|
|
or WH-phrase.
|
||
|
|
|
||
|
|
\end{document}
|
||
|
|
|
||
|
|
----
|
||
|
|
|
||
|
|
=== Latex alternative: Lyx
|
||
|
|
|
||
|
|
[%step]
|
||
|
|
* WYSIWYG latex editor
|
||
|
|
* Documents are generated in .lyx, a subset of latex
|
||
|
|
* Can be used together with version control
|
||
|
|
* Provides, by default, templates for many of the biggest scientific journals
|
||
|
|
|
||
|
|
=== Lyx: example
|
||
|
|
|
||
|
|
image::nvbqz.png[]
|
||
|
|
|
||
|
|
=== Lyx: example II
|
||
|
|
|
||
|
|
image::lyxlilipond.png[]
|
||
|
|
|
||
|
|
|
||
|
|
=== Lightweight Markup languages
|
||
|
|
|
||
|
|
[%step]
|
||
|
|
* Also called Plain Text Markup or humane markup language
|
||
|
|
* Provide a way of formating the document, while still being readable
|
||
|
|
* Widely used on websites and code documentation
|
||
|
|
|
||
|
|
=== LML: current options
|
||
|
|
|
||
|
|
* Markdown
|
||
|
|
* reStructuredText (rst)
|
||
|
|
* Asciidoc
|
||
|
|
|
||
|
|
=== Markdown
|
||
|
|
|
||
|
|
[%step]
|
||
|
|
* Created for minimal formating of web text
|
||
|
|
* used **__everywhere__**: web, jupyter notebooks, r-markdown...
|
||
|
|
* There is no standard, currently exist many flavours of it (github, commonmark, pandoc)
|
||
|
|
* Originally not intended for documents, very limited
|
||
|
|
* Different flavors and tools try to overcome this limitation
|
||
|
|
** (+ pandoc)
|
||
|
|
|
||
|
|
=== Markdown: example
|
||
|
|
|
||
|
|
image::quicktourexample_small.png[]
|
||
|
|
|
||
|
|
=== Asciidoc
|
||
|
|
|
||
|
|
[%step]
|
||
|
|
* Developed for book creation.
|
||
|
|
* Limited number of users
|
||
|
|
* Standardized and extensible, great documentation
|
||
|
|
* Lack of resources makes that bugs or request take time to be fixed
|
||
|
|
|
||
|
|
=== reStructuredText
|
||
|
|
|
||
|
|
[%step]
|
||
|
|
* Originally intended for python documentation
|
||
|
|
* medium sized but very tech-savvy community
|
||
|
|
* Syntax is a little different than the other two
|
||
|
|
* Very powerful and extensible
|
||
|
|
|
||
|
|
|
||
|
|
=== Which one to use?
|
||
|
|
|
||
|
|
* Notetaking:
|
||
|
|
** Markdown
|
||
|
|
** Asciidoc
|
||
|
|
** reStructuredText
|
||
|
|
* Anything more serious:
|
||
|
|
** reStructuredText
|
||
|
|
** Latex/Lyx
|
||
|
|
|
||
|
|
== Resources
|
||
|
|
|
||
|
|
https://chocolatey.org
|
||
|
|
|
||
|
|
----
|
||
|
|
choco install git vscode pandoc
|
||
|
|
----
|
||
|
|
|
||
|
|
|
||
|
|
== Questions?
|
||
|
|
|