git_training.tex

\documentclass[14pt,aspectratio=1610]{beamer} %,draft  % !TEX program = xelatex


% \usefonttheme{sanserif}

% \usetheme{Pittsburgh}%
\usecolortheme{orchid}


\setbeamersize{text margin left=.1in,text margin right=.1in}
\setbeamersize{sidebar width left=1cm, sidebar width right=1cm}

\setbeamertemplate{sidebar right}{}
\setbeamertemplate{footline}{%
\hfill
\hspace{1cm}\insertframenumber{}} %/\inserttotalframenumber

\usepackage{graphicx}
\graphicspath{{./diagrams/}}
% \graphicspath{{diagrams/}}

\usepackage{amssymb, amsfonts, amsmath}
\usepackage[outdir=./diagrams/]{epstopdf}



\newcommand{\C}{\mathbb{C}}
\newcommand{\bR}{\mathbb{R}}
\newcommand{\bP}{\mathbb{P}}

\newcommand{\sE}{\mathcal{E}}
\newcommand{\sL}{\mathcal{L}}
\newcommand{\sM}{\mathcal{M}}
\newcommand{\sS}{\mathcal{S}}


\newcommand{\vpad}[1]{\raise0.5pt\hbox{\vphantom{$#1$}}#1}
% \newcommand{\vpad}[1]{#1}
\newcommand{\overbar}[1]{\mkern1.5mu\overline{\mkern-1.5mu#1\mkern-1.5mu}\mkern1.5mu}
% \newcommand{\overbar}[1]{#1}

\newcommand{\Tb}{\overbar{\vpad\Theta}}
\newcommand{\boldG}{\mathbf{G}}
\newcommand{\Gb}{\overbar{\vpad\boldG}}
\newcommand{\CL}{\mathcal{L}}
\newcommand{\Lb}{\overbar{\vpad\LL}}
\newcommand{\Z}{\mathbf{Z}}
\newcommand{\Zb}{\overbar{\vpad\Z}}
\newcommand{\D}{\mathbf{D}}
\newcommand{\Db}{\overbar{\vpad\D}}
\newcommand{\zz}{\mathbf{z}}
\newcommand{\zzb}{\overline\zz}


\newcommand{\bF}{\mathbf{f}}
\newcommand{\bx}{\mathbf{x}}
\newcommand{\bp}{\mathbf{p}}

\newcommand{\calC}{\mathcal{C}}
\newcommand{\calK}{\mathcal{K}}

\newcommand{\jth}{$j^{\textnormal{th}}$}

\newcommand{\x}{\mathbf{x}}
\newcommand{\z}{\mathbf{z}}
\newcommand{\y}{\mathbf{y}}
\newcommand{\p}{\mathbf{p}}

\usepackage{multirow}
\usepackage[normalem]{ulem}


\usepackage[]{listings}
\lstset{
language=C++,
               basicstyle=\ttfamily,
                keywordstyle=\color{blue}\ttfamily,
                stringstyle=\color{red}\ttfamily,
                commentstyle=\color{green}\ttfamily,
                morecomment=[l][\color{magenta}]{\#}}


% \usepackage{coloremoji}
\setbeamertemplate{footline}[frame number] % except I kind of like 
                                           % including the frame number
\title[Git @ ICERM \hspace{2.5in} Brake]{A \LaTeX-oriented intro to Git \\  \small the tex part is in the interactive demo not in the slides}
\author{Danielle Amethyst Brake}
\date{}



\newcommand{\fframe}[2]{
   \begin{frame}
\frametitle{#1}
#2
\end{frame}
}

\newtheorem{concl}{Conclusion}

\usepackage{verbatim}

\usepackage{hyperref}

\begin{document}
\setbeamertemplate{navigation symbols}{}


%----------- titlepage ----------------------------------------------%
\begin{frame}

 \titlepage
 
 \begin{center}
\end{center}

\vspace{-1.5in}
\small
22 October - 26 November, 2018 \\ \qquad {\footnotesize ICERM Semester on Nonlinear Algebra} \\31 October - 1 November, 2019 with Martin Skrodzki \\ \qquad {\footnotesize ICERM Semester on Illustrating Mathematics}


  \includegraphics[height=0.5in]{UWEC-stacked-wordmark-Blue_cmyk}
\hfill
 \includegraphics[height=0.5in]{Power-of-AND_stckd_blu_CMYK}

\end{frame}


\AtBeginSection[]
{

{
\usebackgroundtemplate{\includegraphics[width=\paperwidth]{diagrams/crystalbackground.jpg}}%


  \begin{frame}
      \frametitle{Outline}
      \tableofcontents[currentsection]
  \end{frame}
  }
}













%                              _________ _       _________ _______  _______ 
%                              \__   __/( (    /|\__   __/(  ____ )(  ___  )
%                                 ) (   |  \  ( |   ) (   | (    )|| (   ) |
%                                 | |   |   \ | |   | |   | (____)|| |   | |
%                                 | |   | (\ \) |   | |   |     __)| |   | |
%                                 | |   | | \   |   | |   | (\ (   | |   | |
%                              ___) (___| )  \  |   | |   | ) \ \__| (___) |
%                              \_______/|/    )_)   )_(   |/   \__/(_______)
           
\fframe{Outcomes from these four sessions}
{
	\begin{itemize}
		\item Make a repo, commit to it
		\item Basic skills for working with a Github hosted repo
		\item Pushing, pulling
		\item Branching, mergine
		\item Forking, issues, pull requests
	\end{itemize}

	\vspace{\baselineskip}

	This is *a lot*.  
}                                  

\fframe{}
{
	\begin{center}
\includegraphics[height=3.5in]{diagrams/git_2x.png}\\xkcd 1597
	\end{center}
}

\section{Session 1 -- Intro to git}



\fframe{What is git?}
{
\begin{definition}
	{\tt git} is a command-line program that records differences in files.
\end{definition}
\vspace{\baselineskip}

	{\em and how is that different from github?}

\vspace{\baselineskip}
	good question, my friend.  
	\begin{definition}
	GitHub is a social media site build around {\tt git} repositories.  
	\end{definition}
}


\fframe{What are words related to Git?}
{
	\begin{columns}[t]
	\column{2in}
	Repo-focused words
	\begin{itemize}
		\item version control software
		\item repository / repo
		\item commit
		\item clone
		\item remote
		\item reset
		\item {\tt .gitignore}


		
	\end{itemize}

	\column{2in}
	Commit-focused words
	\begin{itemize}		
		\item branch
		\item rebase
		\item fast-forward
		\item merge
		\item fetch
		\item pull
		\item conflict
	\end{itemize}
	\end{columns}
}





\fframe{What's a commit?}{

\begin{definition}
A {\bf commit} is a set of differences -- additions and subtractions of lines in file -- together with a message describing them
\end{definition}
}

\fframe{What's a repo?}
{  
\begin{definition}
A {\bf repository} is a folder, together with a subfolder containing special git files. 
\end{definition}

 Don't screw with these special files.  They live in {\tt .git/} inside the repo folder.  

\vfill 

 \tiny Ok, sometimes you need to adjust them...
}
                    
\fframe{What should I version control?}
{
	✅ Use git for these: 
	\begin{itemize}
		\item Files that can be meaningfully-diffed (think text files), and 
		\item static non-diffable files (think images that don't change)
	\end{itemize}

\vspace{\baselineskip}

	🚫 do NOT use git for version control for these:
	\begin{itemize}
		\item generated files (pdf's, executables)
		\item temporary files
		\item word documents (but you wouldn't use word anyway, would you? 😦)
	\end{itemize}
}






\fframe{How do i make a repository?}
{
	\begin{enumerate}
		\item make a new folder, or move to an existing one
		\item {\tt git init}
	\end{enumerate}

\vspace{\baselineskip}

👀	look around in the folder.  does it look different?
}


\fframe{How do i commit?}
{
	\begin{enumerate}
		\item make some changes
		\item {\tt git add filename.ext}
		\item {\tt git commit}
		\item write a commit message
		\item save `file' for commit message, done
	\end{enumerate}
}

\fframe{What's a good commit message?}
{
	\begin{enumerate}
		\item a short summary, like 3-10 words
		\item some longer description
	\end{enumerate}

\begin{itemize}
		\item 🚫 no vague crappy messages that utterly fail to describe your changes
		\item ✅ a message to your future self
	\end{itemize}
}

\fframe{How do I prevent myself from adding temp files?}
{
	🔴 Be very careful to not ever add a temp file, because once it starts tracking, it's there forever.  

\vspace{\baselineskip}
	Use {\tt .gitignore}, a file at root level (in the repo), that describes patterns for files to ignore.

\vfill
	protip: {\tt .gitignore} is cumulative in subdirectories, and you can un-ignore things too
}


\fframe{How do I delete files?}
{
	\begin{enumerate}
		\item Delete the file in your local clone
		\item {\tt git add deletedfile.ext}
		\item {\tt git commit}
	\end{enumerate}

	or just

	\begin{enumerate}
		\item {\tt git delete file} -- all in one
	\end{enumerate}
}


\fframe{What if I mess up?}
{
	Don't mess up.   JK, but seriously, don't mess up.

\vspace{\baselineskip}

	You cannot delete commits from a repo.  
	\begin{itemize}
		\item You {\bf revert} them with the inverse commit.   
		\item You can delete branches... and maybe lose work
		\item You can delete repos... and maybe lose work
	\end{itemize}
}









\fframe{Things I haven't talked about yet}
{
	\begin{itemize}
		\item {\bf Merge conflicts} -- helping solve the ``hot copy'' problem
		\item GitHub
		\item Alternatives to GitHub
		\item Using Git as a time machine
		\item Alternatives to Git
		\item Branching models
		\item Rebasing, pulling, fast-forwarding
	\end{itemize}
}



\fframe{Practice time!}
{
Things to practice:
	\begin{enumerate}
		\item Make some changes
		\item Commit your changes ({\tt git commit})
	\end{enumerate}

	Things to research:
	\begin{itemize}
		\item Deleting files ({\tt git rm})
		\item Renaming files ({\tt git mv})
		\item Writing your commit message in the same command as committing ({\tt git commit -m "arst"})
	\end{itemize}
}




























\section{Session 2 -- GitHub as a Git server}

\fframe{GitHub-specific things}
{
		\begin{columns}[t]
	\column{2in}
	Repo-focused words
	\begin{itemize}
		\item fork
		\item clone
		\item issue


		
	\end{itemize}

	\column{2in}
	Commit- or branch-focused words
	\begin{itemize}		
		\item pull request
	\end{itemize}
	\end{columns}
}




\fframe{}
{\begin{center}\includegraphics[width=4in]{git_usage.pdf}\end{center}}


\fframe{Game plan for teaching}
{

We'll do these things:
	\begin{enumerate}
 
		\item make a new repo on github
		\item clone
		\item commit
		\item push 

	\end{enumerate}

and give overviews for these:
	\begin{itemize}
		\item remotes
		\item pulling and pushin
		\item merges and conflicts
	\end{itemize}
	
}



\fframe{1. new}
{Let's make a git repository on Github.  

\vspace{\baselineskip}
$\Rightarrow$ Follow along on the projector
\vspace{\baselineskip}

\vfill

\hrule

\vspace{\baselineskip}

If you pay GitHub, you can make your repos private

\vspace{\baselineskip}

\qquad $\rightarrow$ Yes, I pay for that service \\
\qquad $\Rightarrow$ (no, i don't, they have free4academic going)

\vspace{\baselineskip}

🎯 we won't make a repo on our local computer this time
}

\fframe{What is a clone?}
{
\begin{definition}
	A {\bf clone} is a repo that has been ``cloned'' from another with {\tt git clone}.  The source is a {\em remote}
\end{definition}

	\vspace{\baselineskip}

	\begin{itemize}
		\item It's a copy of the original repo, in terms of commits.  
		\item It's only an identical copy when cloned.  it's expected to diverge by committing...
	\end{itemize}
}

\fframe{2. clone}
{
	on your local machine, from the terminal
	\begin{enumerate}
		\item move to a location you want the repo's folder to be \\ \quad
		{\tt cd /path/to/folder}
		\item type \\
		\quad {\tt git clone https://github.com/username/reponame}
		\item look 👀 around \\ \quad {\tt ls} 
\end{enumerate}
}

\fframe{3. commit}
{
while 1
\begin{enumerate}
	\item make some changes
	\item {\bf add} the changed files
	\item {\bf commit}
\end{enumerate}
}



\fframe{4. get that data online}
{
	now we'll push.
	\begin{definition}
to {\bf push} is a git action, meaning to make a sequence of {\em commits} appear in another repo
	\end{definition}

	\vspace{\baselineskip}

	\begin{itemize}
	\item all existing commits in {\tt remote} must be present to push.  
	\item hence, pull before you push.  this often makes no difference in a one-person project
	\item typically, you push to origin, which is where the repo came from when cloned
	\end{itemize}
}





\fframe{Why use a git server? Collaboration}
{

	there are many ways to use git to share code \\(focusing on github here).  


	\vspace{\baselineskip}
	here are 2 main ways:

\vspace{\baselineskip}
	\begin{itemize}
	\item add all members as collaborators, all people commit directly to repo
	\item each person forks, and resolve via pull requests
\end{itemize}

\vspace{\baselineskip}

they both have advantages and disadvantages.  We get to choose.  
	\begin{itemize}
	\item Collaborating will lead to merge conflicts sooner
	\item Forking will let us learn about forking and PR's.  This will happen in session 4.
\end{itemize}
}





\fframe{pull, fetch, merge -- defn}
{
\begin{definition}
to {\bf pull} is a git action, meaning to fetch-and-merge from a remote
	\end{definition}

	\begin{definition}
to {\bf fetch} is a git action, to query available branches and commits
	\end{definition}

\begin{definition}
to {\bf merge} is a git action, meaning to make a sequence of commits appear in the current repo.  you get the commits from a branch, either {\em locally} or from a {\em remote}
	\end{definition}

	some speech using the diagram is necessary here
}


\fframe{merge conflict}
{
	git tracks diffs on diffable files.  it's pretty smart about disjoint modifications to a file, but sometimes... it can't tell what you want to do.

		\begin{itemize}
	\item a merge conflict isn't bad
	\item the conflict is resolved when the conflicted file is marked as saved.  
	\item i honestly use a visual tool for this and don't know how to do it command line.  
	\item i totally use visual diff tools.  
\end{itemize}
}






























\section{Session 3 - Branching and merging}

\fframe{What if I have multiple things to work on at once?}
{
	{\bf Branches} solve the problem of working on multiple facets of a project.  They're separate commit-sequences that you can make converge by {\tt merging}

	\vspace{\baselineskip}

	\begin{itemize}
		\item Make a new branch via {\tt git branch newbranchname}
		\item Convege a branch into your current by {\tt git merge branchtomerge}
		\item Get a branch from a remote via {\tt git checkout existingbranchname}
		\item Update your branch list and commit status with {\tt git fetch [remotename]}
	\end{itemize}

}


\fframe{relevant branch words}
{
	 \begin{itemize}
		\item {\tt branch}
		\item {\tt checkout}
		\item {\tt merge}
		\item {\tt fetch}
		\item {\tt pull}
		\item {\tt stash}
	\end{itemize}
}


\fframe{make a branch}
{do it now.  either in a GUI or in the terminal

\vspace{\baselineskip}

{\tt git branch branchname}

\vspace{\baselineskip}

✅ you can totally make up "folders" for your branches, and branch from branches, etc.
}



\fframe{make a commit}
{do it now.  either in a GUI or in the terminal}

\fframe{make a switch back to {\tt master} branch}
{do it now.  either in a GUI or in the terminal


\vspace{\baselineskip}

now look around at the file you edited.  what do you notice?
}

\fframe{branch again, from master}
{
	{\tt git branch branchname2}
}


\fframe{make a commit}
{
do it now.  


\vspace{\baselineskip}

✅ 
please, DO modify the same area of a file you edited in the other branch-commit exercise.  (i have a reason you should do this)

}


\fframe{now we'll merge in the first branch}
{
	\begin{enumerate}
		\item switch back to {\tt master}
		\item {\tt git merge  branchname}
		\item [optional] -- {\tt git branch -d branchname}
	\end{enumerate}

\vspace{\baselineskip}

	this is done at the end of a branch's life, often, when you are done with a feature (sequence of commits focused on one thing)
}

\fframe{merge in the second branch}
{
	same process.  be in branch you want the commits to end up in, and merge the other branch into it.

\vspace{\baselineskip}

		\begin{enumerate}
		\item switch back to {\tt master}
		\item {\tt git merge  branchname2}
		\item [optional] -- {\tt git branch -d branchname2}
	\end{enumerate}

	if we've done it right, we'll get a merge conflict problem.  
}




\fframe{What's a merge conflict?}
{
	git records differences in files.

	if a patch (diffset) is attempted to be applied on top of a set of commits that record changes in the same portions of a file, it's a {\bf merge conflict}.

}

\fframe{Get some tools to help}
{
	I turn to GUI tools at this point, honestly.

	There are lots of tools you can use.  Choose one for 
	\begin{itemize}
		\item git itself.  i do not recommend the GitHub app, unless you are hosting origin at GitHub.
		\item merging.  do a search right now for tools for this.  
		OSX users -- XCode comes with FileMerge, and it's not terrible.
		\end{itemize} 


}

\fframe{How to resolve a merge conflict}
{

		\begin{enumerate}
			\item goto the repo in the git tool, and use the UI to 'launch external merge tool' on the conflicted files.
			\item use the merge tool to resolve conflicts, choosing right, left, both, neither, or hand-editing.
			\item save
			\item test.  goto 2?
			\item quit the merge tool
			\item return to the git tool.  finish the commit to finish the merge.  
		\end{enumerate}

}



\fframe{things you should know}
{
\begin{itemize}
		\item If things get FUBAR, {\tt git reset --hard} will, well, reset your repo to before you started the merge.  just start over
		\item beware accentally committing partially merged files.  you get diff crap left in the file, and it's annoying
		\item You might consider doing the merge from master into feature, then merge feature into master, to make any mistakes appear in feature.
	\end{itemize}
}










\section{Session 4 - Github and branching}

\fframe{Github features}
{
\begin{itemize}
	\item Forking
	\item Pull requests
	\item Issues
\end{itemize}
}


\fframe{Fork}
{
	\begin{definition}
to {\bf fork} is a Github action, meaning to take a clone from one user's repository, and associate it as upstream
	\end{definition}

	\begin{definition}
we say A is {\bf upstream} of B when A is a remote of B, and Github has stored that direction in the association graph
	\end{definition}

	let's use that diagram again
}


\fframe{Pull request}
{
	\begin{definition}
		a {\bf pull request} is a Github thing that requests that an owner of a repo A from which a fork B has been taken, pull from B into A.
	\end{definition}

	Pull requests (PRs) facilitate discussion around blobs of commits, and the resolution of the merge.

	They're helpful because, if you don't have this service, how do you let the other person know that you're ready to share your new changes / code?
}

\fframe{notes on PRs}
{
\begin{itemize}
	\item Pull requests are often made from branches on the fork.  In fact, when you make the PR, you choose the from/to branch.
	\item Sometimes it is nice to generate PRs, even if you control both repos, for generating records.
\end{itemize}

let's make a PR.  
}



\fframe{together, let's}
{
	\begin{enumerate}
		\item fork a friend's repo
		\item clone to our computer
		\item branch
		\item commit to that branch
		\item push to origin
		\item make the PR
		\item resolve the PR
	\end{enumerate}
}

\fframe{Issues}
{
	\begin{definition}
an {\bf issue} is a github thread of conversation focused on one topic related to the repo.
	\end{definition}

}


\fframe{notes on issues}
{
	\begin{itemize}
\item Issues are unique to the repo.  Forks don't carry issues.
\item Issues and PR's form a sequence starting at 1.  \#1 is the first issue/PR for that repo
\item Use {\bf labels}  to good effect.  Github pre-populates a list for you these days
\item Hide irrelevant posts in the thread to help your users
\item Think about having a policy on the README or on your Wiki that describes the etiquette expected in your issues page
	\end{itemize}
}

\fframe{Let's make issues}
{
\begin{enumerate}
	\item Find a friend's repo
	\item Start an issue
\end{enumerate}

\vspace{\baselineskip}
This part will be done in a browser
}


\section*{---}
\fframe{What else would you like to talk about?}
{
	???
}





\usebackgroundtemplate{\includegraphics[width=\paperwidth]{diagrams/medley_croi_sol_tob_hel_ste_him.jpg}}%
\fframe{Thank you!}{


}











\end{document}