\documentclass{article}
\usepackage[T1]{fontenc}
\usepackage[a4paper, margin=0.75in]{geometry}

% set up hyperlink coloring
\usepackage{hyperref}
\hypersetup{
    colorlinks=true,
    linkcolor=blue,
    filecolor=magenta,
    urlcolor=cyan
}

\setlength{\parindent}{0pt} % no indentation

\renewcommand{\familydefault}{\sfdefault} % default to sans serif

% code support: listings and fancy verbatim
\usepackage{listings}
\lstset{basicstyle=\ttfamily\footnotesize}
\usepackage{fancyvrb}

\renewcommand{\familydefault}{\sfdefault} % default to sans serif

%%%%%%%%%%%%%%%%
\begin{document}

\title{Homework 3\\Git}
\author{EECS 201 Winter 2020}
\date{}
\maketitle

\section*{Submission Instructions}
This homework will be submitted as a repository on the UMich GitLab server.
This will become evident as you work through the assignment.

\section*{Preface}
Git has an interesting conundrum where to use Git you need to have some understanding of Git,
but to understand Git you need to have some experience using Git.
While this class' goal is to help you become more independent problem solvers,
this circular dependency may make Git hard to get into,
so for this homework we'll give a guided introduction.
\\\\
Some other tutorials/resouces you can look at besides the \href{https://git-scm.com/docs}{official documentation} and \href{https://git-scm.com/book/en/v2}{\textit{Pro Git}}:
\begin{itemize}
    \item \href{https://www.atlassian.com/git/tutorials}{Atlassian's tutorials}
          \\{\footnotesize Atlassian is the company that made BitBucket, JIRA, and Confluence}
    \item \href{http://pcottle.github.io/learnGitBranching/}{Interactive branching game}
    \item \href{http://adriansampson.net/blog/git.html}{A humorous quick-reference guide}
    \item \href{http://ohshitgit.com/}{A more humorous quick-reference guide (language warning)}
\end{itemize}

In this introduction we will be taking an existing codebase and turning it into a Git repository.
The process of doing this is an empty directory is exactly the same:
instead of an empty directory we have untracked files that are already provided.

\section{GITing started}
You are in charge of migrating a small command line calculator program from an archaic,
proprietary version control system whose company became defunct in the 90s to Git
as well as handling the remaining issues in the code.

First, we'll need to acquire the code:
\begin{Verbatim}[fontsize=\footnotesize]
  $ wget https://www.eecs.umich.edu/courses/eecs201/files/assignments/hw3-calculator.tar.gz
  $ # e(X)tract (Z)ipped (F)ile
  $ tar xzf hw3-calculator.tar.gz
\end{Verbatim}

\begin{enumerate}
    \item Download and extract the code. \texttt{cd} into the extracted directory.
    \item Let's play around a bit with the application.
          Run \texttt{make} to build the application.
          Familiarize yourself with the source code in \texttt{src} and \texttt{inc}.
    \item Try running \texttt{\$ ./calculate 3 x 3}
    \item Let's git started. Initialize a Git repository with \texttt{git init}.
    \item Ignoring my advice in lecture let's blindly add all the files in the current directory with \texttt{git add .}
    \item Run \texttt{git status} to see what's currently in the Index
          (get into the habit of running \texttt{git status};
          it'll tell you a lot about what's going on).
    \item Notice how we have the final compiled binary \texttt{calculate} and intermediate object code files in \texttt{obj} in the Index.
          In general, we don't want to version the intermediate and final build outputs as they're the products of the code that we are versioning;
          no reason to version a thing twice.
          Other things that we don't tend to version include development environment specific things,
          like logs, other output files, or core dumps that your application produces during runtime,
          and developer system dependent things like editor swap files and weird filesystem helper files like \texttt{.DS\_STORE}.
    \item Use \texttt{git reset} to unstage the \texttt{calculate} binary and files under \texttt{obj}. If your OS or filesystem creates any other junk specific to it (like \texttt{.DS\_STORE} on macOS), unstage those as well.
    \item Use \texttt{git commit} to make this initial check-in/commit of the codebase.
          Be sure to make a commit message that follows best practices as mentioned in class.
    \item Run \texttt{\$ git status} for good measure.
          Isn't seeing \texttt{calculate} and \texttt{obj/} as untracked files annoying?
          Figure out a way to get \textit{Git} to locally \textit{ignore} the intermediate and final build outputs,
          staging the necessary file(s) and making a commit.
          If your OS, filesystem (or text editor) creates files like \texttt{.DS\_STORE} or \texttt{*.swp} files,
          you may want to look into a way to ignore such files \texttt{globally}.
    \item Run \texttt{\$ make clean} to delete the intermediate and final build outputs.
    \item Create a README file that explains how to build and clean the application. Stage and commit it.
    \item \texttt{rm} the \texttt{Makefile} and delete a character from the README.
    \item Recover the deleted \texttt{Makefile} undo the changes to the README using \texttt{git checkout} or \texttt{git restore}.
\end{enumerate}

Hooray! We've migrated the application to Git.
Now we have to move onto fixing our problems.

\section{GITing around}
\begin{enumerate}
    \item Take note of the comments that mention an issue in the source code.
    \item From here, we are going to make two \texttt{topic branches} that deal with each of the issues.
          Use \texttt{git branch} to create branches \texttt{issue149} and \texttt{issue221} that correspond to the issues mentioned in the comments.
    \item Switch to one of topic branches using \texttt{git checkout} or \texttt{git switch} and perform its corresponding fixes.
    \begin{enumerate}
        \item Make sure to delete the comment mentioning the issue in the code, as you have now dealt with it.
        \item For Issue 221, when handling the divide by zero return status, returning the proper code and print ``Divide by 0'' with a newline to \texttt{stderr}.
    \end{enumerate}
    \item Use \texttt{git diff} to see how your files have changed.
    \item Use \texttt{git add -u} to add files that you have modified. If you have staged files that are unrelated to this issue, be sure to unstage them as this branch is focused on fixing the appropriate issue.
    \item Commit the fix, making sure to have a properly formatted and descriptive title and body for the commit message as well as including a reference to the issue number in the \textbf{body}.
    \item Repeat steps 3 to 6 for the other branch.
    \item Switch to the \texttt{master} branch.
    \item Now we are going to bring the commits from the topic branches over to the \texttt{master} branch.
    \item Use \texttt{git merge} to bring over the commits from one of the topic branches.
          Note that this topic branch and \texttt{master} \textbf{have not} diverged, making this process painless.
          This is known as \texttt{fast-forwarding}, where a branch just moves its pointer up.
    \item Use \texttt{git merge} to bring over the commits from the remaining topic branch.
          Note that this topic and \texttt{master} \textbf{have} diverged with the topic branch being
          a commit or two (or more) behind \texttt{master}.
          This will necessitate a special \textit{merge commit} that gets automatically generated
          (which you don't have to reword for this assignment).
          If the merge has to stop due to not being automatically resolved,
          use \texttt{git status} to see where the merge conflict is occurring and modify the files
          to get them into working order, then complete the merge.
    \item Run \texttt{\$ git show} to see what this latest commit entails.
    \item Run \texttt{\$ git show HEAD\^{}1} or \texttt{\$ git show HEAD\^} to see the first parent of this merge commit.
    \item Run \texttt{\$ git show HEAD\^{}2} to see the second parent of this merge commit.
    \item Use \texttt{git log} to show you the list of commits.
\end{enumerate}

Now that your job is finished, let's push it to a remote repository.

\section{\href{https://www.youtube.com/watch?v=wBTsFZGzoho}{You're going surfing on the internet!}}
\begin{enumerate}
    \item Log into \url{https://gitlab.umich.edu} and set up your UMich GitLab account.
          \textbf{(Don't mistake this for the EECS department's GitLab server gitlab.eecs.umich.edu!)}
    \item Set up SSH with your UMich Gitlab account (if you haven't already).
          You can find this under your account settings > SSH Keys,
          and the site has a guide on how to set it up.
          This allows you to painlessly clone/pull/push with the UMich Gitlab server.
          (The counterpart to SSH is HTTPS, but SSH is seriously easier to work with on a regular basis).
    \item Create a completely blank, new \textbf{private} "Project" (i.e. remote repository) with exactly the name:
          \texttt{eecs201-hw3}
    \item Let's now set up this UMich Gitlab project as the remote for your local repository.
    \item Add it as the \texttt{origin}: \texttt{\$ git remote add origin git@gitlab.umich.edu:<your uniqname>/eecs201-hw3.git}. This uses \texttt{git remote} to add a remote named \texttt{origin} with a specified SSH URL.
    \item Now let's push the all commits from all the branches to the remote:
          \texttt{\$ git push -u origin --all}.
          \texttt{-u} sets the upstream tracking information for the local branches, allowing them to push/pull commits from the remote branches.
          \texttt{origin} is the remote that we are referring to.
          \texttt{{-}{-}all} pushes all of the branches. You could instead, say, push only \texttt{master}.
    \item In the UMich GitLab project's Settings>Members add the course staff \texttt{brng} and \texttt{computer} as Reporters.
          As part of the grading process for this homework we will be looking at your repositories on the UMich Gitlab.
    \item Back in your local repository, make sure you are in \texttt{master}.
    \item Create a file called \texttt{report.txt}.
    \item On the first line of the file, put down an estimate of how long you took to do this assignment
          in minutes as an integer (e.g. ``37'', ``84'': just numbers, no letters).
    \item On the second line and onwards of the file, put down what you learned (if anything)
          by doing this assignment. If you already knew how to do all of this, just put ``N/A''.
    \item Stage and commit this \texttt{report.txt}.
    \item Use \texttt{git push} to push this commit to your UMich GitLab repository.
\end{enumerate}

\end{document}
