Slides_GIT_Mariano/presentation.adoc

Document Version Control with GIT

Before we start…​

What is version control?

• 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?

• 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

• Remote backup of files

• Powerful tool for collaboration

GIT

• Developed by Linus Torvalds in 2005

• The linux Kernel:

  • ~63000 files

  • Roughly 15,600 developers from more than 1,400 companies

Characteristics

• Free and open source

• Distributed

• Powerful and flexible

• Learning curve can be steep

!

How does it work?

Installation

https://git-scm.com/download/win

Package managers are heavily recommended!

Creating a remote repository

• 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

copying remote repository: clone

• git clone repository

• Clones the remote repository into the local one

staging changes (local)

• git add files

• Adds the changes into the local staging area

Saving changes: commit (local)

• 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)

• 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

• git push

• Uploads the state of the local repository to the remote one

Download from remote repository: pull

• 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

other (advanced) stuff

• tags

• partial reverts

• change history

• …​

Docs as code

• 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

• 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…​

• The most common document formats: word, pdf…​ are binary files

• git (text based) doesn’t work with them

Solutions?

• 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

• 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

• 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

• 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

• 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

Lyx: example II

Lightweight Markup languages

• 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

• 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

Asciidoc

• 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

• 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?